Merge lp:~jml/launchpad/silence-sphinx-errors-and-warnings into lp:launchpad

[Jonathan Lange]

Fix rST and Sphinx errors in our top-level docs, and make the main page more interesting.

Fixes up the documentation in doc/ so that 'make -C doc html' builds successfully without producing any warnings. Also changes the index page to be a little nicer and more structured.

I've tweaked the formatting of some of the old docs so they are a little more rST-friendly, but I haven't gone overboard. I also haven't exercised much editorial power, other than imposing some kind of organization on the docs.

I'll land a branch in future that prevents new documentation warnings. Such a change should be fairly unintrusive, since it will only affect people editing documentation, who should be getting it right anyway.

To test, run::
  make -C doc html

The documentation can be viewed in your browser in doc/_build/html/index.html.

[Данило Шеган (danilo)]

Thanks for the branch.

review: Approve

=== modified file 'doc/buildout.txt'
--- doc/buildout.txt	2010-07-25 17:47:41 +0000
+++ doc/buildout.txt	2011-02-16 14:43:33 +0000
@@ -599,7 +599,7 @@
 being picked up instantly without us having to create a distribution.
 
 To do this add the extra paths to the ``develop`` key in the ``[buildout]``
-section of ``buildout.cfg"::
+section of ``buildout.cfg``::
 
     [buildout]
     develop = .
 
=== modified file 'doc/chameleon.txt'
--- doc/chameleon.txt	2009-05-27 22:32:01 +0000
+++ doc/chameleon.txt	2011-02-16 14:43:33 +0000
@@ -1,7 +1,7 @@
 Running Launchpad with Chameleon Template Engine
 ================================================
 
-- Need to pull the following dependencies into ``sourcecode``::
+- Need to pull the following dependencies into ``sourcecode``:
 
   - lp:sourcecodegen/trunk
   - lp:chameleon.core/trunk
@@ -14,7 +14,8 @@
   ``z3c.pt`` and use ``zope.pagetemplate`` instead. Yes, it's that
   simple. This is possible thanks to ``z3c.ptcompat``.
 
-- Other useful environment options for ``z3c.pt``::
+
+Other useful environment options for ``z3c.pt``::
 
   # in debug-mode, templates on disk are reloaded if they're modified
   CHAMELEON_DEBUG (default: false)
 
=== added file 'doc/historical.txt'
--- doc/historical.txt	1970-01-01 00:00:00 +0000
+++ doc/historical.txt	2011-02-16 14:43:33 +0000
@@ -0,0 +1,16 @@
+================================
+Documents of historical interest
+================================
+
+The following documents don't really represent current thinking or development
+practices, but are useful to have around to get a sense of where we've been
+and how we've progressed.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   chameleon
+   malone
+   webapp-process
 
=== modified file 'doc/index.txt'
--- doc/index.txt	2011-02-03 16:06:59 +0000
+++ doc/index.txt	2011-02-16 14:43:33 +0000
@@ -3,17 +3,47 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+=================================
 Launchpad developer documentation
 =================================
 
-Contents:
-
-.. toctree::
-   :maxdepth: 1
-
-   README <readme>
-   Launchpad Vision <vision>
-   Launchpad Values <values>
+Welcome to the Launchpad developer documentation.  This documentation is for
+people who want to hack on Launchpad.
+
+Overview
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   readme
+   vision
+   values
+
+Technical
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   buildout
+
+Possibly out-of-date
+--------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   security
+   email
+
+Other
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   historical
 
 
 Indices and tables
 
=== modified file 'doc/malone.txt'
--- doc/malone.txt	2007-10-31 19:03:15 +0000
+++ doc/malone.txt	2011-02-16 14:43:33 +0000
@@ -1,3 +1,6 @@
+============
+About Malone
+============
 
 The world has many excellent bug tracking tools already. It would not make
 sense to create another bugtracker unless the vision behind that software
@@ -6,6 +9,7 @@
 do for the open source community.
 
 The Vision behind Malone
+========================
 
 Malone is a unified bug tracker for the entire open source world. It is
 designed to allow the whole open source community to collaborate on software
@@ -15,15 +19,16 @@
 specific software defect.
 
 Upstream and Distributions
+==========================
 
 A unique feature of Malone is that it understands the structure of the open
-source community:
+source community::
 
   Software is developed by individuals or groups with a common interest in a
   specific problem. We call this group "upstream". That software is
   distributed in its pristine state ("tarballs", usually) and is usually
   designed to be compiled and run on a variety of platforms.
-  
+
   However, most people who use that software will not get it directly from
   upstream, build it and install it locally. They will install a package
   that has already been prepared for the specific platform they are running
@@ -46,6 +51,7 @@
 information very prominently.
 
 Watches
+=======
 
 It's unlikely that the whole world will shift to Malone. Many larger
 projects have their own bug tracking tools (Bugzilla, Sourceforge and
@@ -61,6 +67,7 @@
 would create a BugWatch in the Malone bug pointing at that upstream bug.
 
 Email Integration
+=================
 
 It's important that Malone be usable entirely in email. Many open source
 developers use their email to track work that needs to be done. So all of
@@ -69,6 +76,7 @@
 reports of bugs on a product or distrbution.
 
 Distribution Bugs
+=================
 
 Malone is designed to track bugs upstream, and in distributions. The
 requirements for a distribution bugtracker are somewhat specialised. A
@@ -83,6 +91,7 @@
 also the precise binary package that manifests the bug.
 
 Milestones and DistroSeries
+===========================
 
 In addition, it's important to be able to know which bugs need to be fix for
 a given release of the distribution, or a given milestone upstream. Malone
@@ -91,6 +100,7 @@
 making towards a release.
 
 Version Tracking
+================
 
 One very difficult problem faced by support teams in the open source world
 is that users may not all be running the latest version of a piece of code.
@@ -98,23 +108,24 @@
 whether a bug is found in a particular version of a package or not.
 
 Future
-
- 1. Bazaar Integration
-    Malone is part of Launchpad, a web based portal for open source
-    developers. Another component of that portal is the Bazaar, a repository
-    of data and metadata about code stored in the Bazaar revision control
-    system. We hope that Bazaar will be embraced by the open source world,
-    as it solves a number of problems with traditional centralised revision
-    control systems and is again designed to support distributed
-    disconnected operation.
-
-    Once more people start keeping their code in Bazaar, it should become
-    possible to streamline the cooperation process even further. For
-    example, if the fix for a particular Malone bug can be found in a Bazaar
-    changeset, then it should be possible for upstream and other
-    distributions to merge in that fix to their codebase automatically and
-    easily. The integration could even be bidirectional - once a fix had been
-    merged in, Bazaar could possibly detect that and mark the bug fixed in
-    that codebase automatically.
+======
+
+Bazaar Integration
+------------------
+
+Malone is part of Launchpad, a web based portal for open source
+developers. Another component of that portal is the Bazaar, a repository of
+data and metadata about code stored in the Bazaar revision control system. We
+hope that Bazaar will be embraced by the open source world, as it solves a
+number of problems with traditional centralised revision control systems and
+is again designed to support distributed disconnected operation.
+
+Once more people start keeping their code in Bazaar, it should become possible
+to streamline the cooperation process even further. For example, if the fix
+for a particular Malone bug can be found in a Bazaar changeset, then it should
+be possible for upstream and other distributions to merge in that fix to their
+codebase automatically and easily. The integration could even be
+bidirectional - once a fix had been merged in, Bazaar could possibly detect
+that and mark the bug fixed in that codebase automatically.
 
 
 
=== modified file 'doc/security.txt'
--- doc/security.txt	2011-02-04 16:53:06 +0000
+++ doc/security.txt	2011-02-16 14:43:33 +0000
@@ -38,7 +38,7 @@
 
 1. Define the adapter in lib/canonical/launchpad/security.py. Here's a simple
 example of an adapter that authorizes only an object owner for the
-launchpad.Edit permission on objects that implement the IHasOwner interface:
+launchpad.Edit permission on objects that implement the IHasOwner interface::
 
     class EditByOwner(AuthorizationBase):
         permission = 'launchpad.Edit'
@@ -54,7 +54,7 @@
 
 2. Declare the permission on a given interface in a zcml file. So, for the
 above adapter, here's how it's hooked up to IProduct, where IProduct is
-protected with the launchpad.Edit permission:
+protected with the launchpad.Edit permission::
 
     <class
         class="lp.registry.model.product.Product">
 
=== modified file 'doc/webapp-process.txt'
--- doc/webapp-process.txt	2010-02-17 11:13:06 +0000
+++ doc/webapp-process.txt	2011-02-16 14:43:33 +0000
@@ -194,7 +194,7 @@
 
 We need to know what types of things are at a particular URL.  Here's an
 example of a typical URL in a web application.  This time, I've included
-the "rosetta" path segment at the root.
+the "rosetta" path segment at the root::
 
   /rosetta/projects/$PACKAGENAME/teams/$TEAM/add-member.html
    |       |        |            |     |     |