Colin Watson has proposed merging ~cjwatson/launchpad:doc-restructuring into launchpad:master.
Commit message: Restructure some bits of the developer documentation Requested reviews: Launchpad code reviewers (launchpad-reviewers) For more details, see: https://code.launchpad.net/~cjwatson/launchpad/+git/launchpad/+merge/426832 These are following up on a call we had with Daniele Procida today, mostly focused on improving the home page. -- Your team Launchpad code reviewers is requested to review the proposed merge of ~cjwatson/launchpad:doc-restructuring into launchpad:master.
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/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
_______________________________________________ Mailing list: https://launchpad.net/~launchpad-reviewers Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-reviewers More help : https://help.launchpad.net/ListHelp
