Merge ~cjwatson/launchpad:doc-restructuring into launchpad:master

[Colin Watson]

Restructure some bits of the developer documentation

These are following up on a call we had with Daniele Procida today, mostly focused on improving the home page.

[Jürgen Gmach (jugmac00)]

review: Approve

diff --git a/README b/README
index d09ef4f..a326348 100644
--- a/README
+++ b/README
@@ -13,11 +13,12 @@ received many contributions from many wonderful people
 
 If you want help using Launchpad, then please visit our help wiki at:
 
-    https://help.launchpad.net
+    https://help.launchpad.net/
 
 If you'd like to contribute to Launchpad, have a look at:
 
-    https://dev.launchpad.net
+    https://launchpad.readthedocs.io/
+    https://dev.launchpad.net/
 
 Alternatively, have a poke around in the code, which you probably already know
 how to get if you are reading this file.
@@ -27,74 +28,15 @@ Getting started
 ===============
 
 There's a full guide for getting up-and-running with a development Launchpad
-environment at <https://dev.launchpad.net/Getting>.  When you are ready to
-submit a patch, please consult <https://dev.launchpad.net/PatchSubmission>.
+environment at
+<https://launchpad.readthedocs.io/en/latest/how-to/running.html>.  When you are
+ready to submit a patch, please consult
+<https://dev.launchpad.net/PatchSubmission>.
 
 Our bug tracker is at <https://bugs.launchpad.net/launchpad/> and you can get
 the source code any time by doing:
 
   $ git clone https://git.launchpad.net/launchpad
 
-
-Navigating the tree
--------------------
-
-The Launchpad tree is big, messy and changing.  Sorry about that.  Don't panic
-though, it can sense fear.  Keep a firm grip on `grep` and pay attention to
-these important top-level folders:
-
-  bin/, utilities/
-    Where you will find scripts intended for developers and admins.  There's
-    no rhyme or reason to what goes in bin/ and what goes in utilities/, so
-    take a look in both.
-
-  configs/
-    Configuration files for various kinds of Launchpad instances.
-    'development' and 'testrunner' are of particular interest to developers.
-
-  cronscripts/
-    Scripts that are run on actual production instances of Launchpad as
-    cronjobs.
-
-  daemons/
-    Entry points for various daemons that form part of Launchpad
-
-  database/
-    Our database schema, our sample data, and some other stuff that causes
-    fear.
-
-  doc/
-    General system-wide documentation. You can also find documentation on
-    <https://dev.launchpad.net>, in docstrings and in doctests.
-
-  lib/
-    Where the vast majority of the code lives, along with our templates, tests
-    and the bits of our documentation that are written as doctests. 'lp' and
-    'canonical' are the two most interesting packages. Note that 'canonical'
-    is deprecated in favour of 'lp'.  To learn more about how the 'lp' package
-    is laid out, take a look at its docstring.
-
-  Makefile
-    Ahh, bliss.  The Makefile has all sorts of goodies.  If you spend any
-    length of time hacking on Launchpad, you'll use it often.  The most
-    important targets are 'make clean', 'make compile', 'make schema', 'make
-    run' and 'make run_all'.
-
-  scripts/
-    Scripts that are run on actual production instances of Launchpad,
-    generally triggered by some automatic process.
-
-
-You can spend years hacking on Launchpad full-time and not know what all of
-the files in the top-level directory are for.  However, here's a guide to some
-of the ones that come up from time to time.
-
-  brzplugins/
-    Breezy plugins used in running Launchpad.
-
-  sourcecode/
-    A directory into which we symlink branches of some of Launchpad's
-    dependencies.  Don't ask.
-
-  zcml/
-    Various configuration files for the Zope services. Angels fear to tread.
+See <https://launchpad.readthedocs.io/en/latest/explanation/navigating.html>
+for advice on navigating the code.
diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst
index bb30f5a..c6b72d0 100644
--- a/doc/explanation/index.rst
+++ b/doc/explanation/index.rst
@@ -8,7 +8,7 @@ Explanation
 
    running-details
    framework
+   navigating
    architecture
    pip
    favicon
-   doc-theme
diff --git a/doc/explanation/navigating.rst b/doc/explanation/navigating.rst
new file mode 100644
index 0000000..277d452
--- /dev/null
+++ b/doc/explanation/navigating.rst
@@ -0,0 +1,67 @@
+===================
+Navigating the tree
+===================
+
+See :doc:`../how-to/running` to learn how to get Launchpad's code and set up
+a local development environment.
+
+The Launchpad tree is big, messy and changing.  Sorry about that.  Don't panic
+though!  Keep a firm grip on ``grep`` and pay attention to
+these important top-level folders:
+
+``bin/``, ``utilities/``
+    Where you will find scripts intended for developers and admins.  There's
+    no rhyme or reason to what goes in bin/ and what goes in utilities/, so
+    take a look in both.
+
+``configs/``
+    Configuration files for various kinds of Launchpad instances.
+    ``development`` and ``testrunner`` are of particular interest to developers.
+
+``cronscripts/``
+    Scripts that are run on actual production instances of Launchpad as
+    cron jobs.
+
+``daemons/``
+    Entry points for various daemons that form part of Launchpad.
+
+``database/``
+    Our database schema, our sample data, and other things related to those.
+
+``doc/``
+    General system-wide documentation. You can also find documentation on
+    the `developer wiki <https://dev.launchpad.net/>`_, in docstrings, and
+    in doctests.
+
+``lib/``
+    Where the vast majority of the code lives, along with our templates,
+    tests, and the bits of our documentation that are written as doctests.
+    ``lp`` is the most interesting package, with ``canonical`` containing
+    some things like images and style sheets.  To learn more about how the
+    ``lp`` package is laid out, take a look at its docstring.
+
+``Makefile``
+    The ``Makefile`` has all sorts of goodies.  If you spend any length of
+    time hacking on Launchpad, you'll use it often.  The most important
+    targets are ``make clean``, ``make compile``, ``make schema``, ``make
+    run`` and ``make run_all``.
+
+``scripts/``
+    Scripts that are run on actual production instances of Launchpad,
+    generally triggered by some automatic process.
+
+
+You can spend years hacking on Launchpad full-time and not know what all of
+the files in the top-level directory are for.  However, here's a guide to some
+of the ones that come up from time to time.
+
+``brzplugins/``
+    Breezy plugins used in running Launchpad.
+
+``sourcecode/``
+    A directory into which we symlink branches of some of Launchpad's
+    dependencies that haven't yet been turned into proper Python
+    dependencies.
+
+``zcml/``
+    Various configuration files for the Zope services.
diff --git a/doc/explanation/doc-theme.rst b/doc/how-to/doc-theme.rst
similarity index 100%
rename from doc/explanation/doc-theme.rst
rename to doc/how-to/doc-theme.rst
diff --git a/doc/how-to/index.rst b/doc/how-to/index.rst
index 86b0543..2324586 100644
--- a/doc/how-to/index.rst
+++ b/doc/how-to/index.rst
@@ -19,3 +19,4 @@ How-to Guides
    land-update-for-loggerhead
    update-configuration-for-testing
    deploying-configuration-changes
+   doc-theme
diff --git a/doc/how-to/running.rst b/doc/how-to/running.rst
index 4fe9fd3..affb999 100644
--- a/doc/how-to/running.rst
+++ b/doc/how-to/running.rst
@@ -12,6 +12,9 @@ own machine, using a `LXD
 <https://linuxcontainers.org/lxd/introduction/>`_-managed container to
 isolate it from the rest of your system.
 
+After you've done this, you may want to read about
+:doc:`../explanation/navigating`.
+
 Supported operating systems
 ===========================
 
diff --git a/doc/index.rst b/doc/index.rst
index 8d2d3a5..2eb87a4 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -5,6 +5,19 @@ Launchpad developer documentation
 Welcome to the Launchpad developer documentation.  This documentation is for
 people who want to hack on Launchpad.
 
+Launchpad is an open source suite of tools that help people and teams to
+work together on software projects.  Unlike many open source projects,
+Launchpad isn't something you install and run yourself (although you are
+welcome to do so), instead, contributors help make `Launchpad
+<https://launchpad.net>`_ better.
+
+If you want help using Launchpad, then please visit our `user documentation
+<https://help.launchpad.net>`_.
+
+If you'd like to contribute to Launchpad, this documentation is for you.
+Alternatively, :doc:`have a poke around in the code <how-to/running>`.
+
+
 Contents
 ========
 
@@ -22,8 +35,6 @@ Overview
 
 .. list-table::
 
-   * - :doc:`readme`
-     - Overview of the Launchpad tree
    * - :doc:`strategy`
      - Why are we making Launchpad, and for whom?
    * - :doc:`scope`
@@ -38,9 +49,11 @@ Overview
 Project and community
 =====================
 
-Launchpad is a member of the Ubuntu family.  It's an open source project
-that warmly welcomes contributions, suggestions, fixes and constructive
-feedback.
+Launchpad is a member of the Ubuntu family, sponsored by `Canonical
+<https://canonical.com/>`_.  It's an open source project that warmly
+welcomes contributions, suggestions, fixes and constructive feedback, and
+has received `many contributions from many wonderful people
+<https://dev.launchpad.net/Contributions>`_.
 
 * `Code of conduct <https://ubuntu.com/community/code-of-conduct>`_
 * `Get help using Launchpad <https://help.launchpad.net/>`_
@@ -56,6 +69,7 @@ Thinking about using Launchpad for your next project?  `Get in touch!
 .. toctree::
    :hidden:
 
+   Home <self>
    how-to/index
    explanation/index
    reference/index
diff --git a/doc/overview.rst b/doc/overview.rst
index 5ff5584..12a41dc 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -6,7 +6,6 @@ Overview
 .. toctree::
    :maxdepth: 1
 
-   readme
    strategy
    scope
    values
diff --git a/doc/readme.rst b/doc/readme.rst
deleted file mode 120000
index 59a23c4..0000000
--- a/doc/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-../README
\ No newline at end of file