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

Proposed by Jonathan Lange
Status: Merged
Approved by: Данило Шеган
Approved revision: no longer in the source branch.
Merged at revision: 12394
Proposed branch: lp:~jml/launchpad/silence-sphinx-errors-and-warnings
Merge into: lp:launchpad
Diff against target: 272 lines (+92/-34)
7 files modified
doc/buildout.txt (+1/-1)
doc/chameleon.txt (+3/-2)
doc/historical.txt (+16/-0)
doc/index.txt (+38/-8)
doc/malone.txt (+31/-20)
doc/security.txt (+2/-2)
doc/webapp-process.txt (+1/-1)
To merge this branch: bzr merge lp:~jml/launchpad/silence-sphinx-errors-and-warnings
Reviewer Review Type Date Requested Status
Данило Шеган (community) Approve
Review via email: mp+49965@code.launchpad.net

Commit message

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

Description of the change

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.

To post a comment you must log in.
Данило Шеган (danilo) wrote :

Thanks for the branch.

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/buildout.txt'
2--- doc/buildout.txt 2010-07-25 17:47:41 +0000
3+++ doc/buildout.txt 2011-02-16 14:43:33 +0000
4@@ -599,7 +599,7 @@
5 being picked up instantly without us having to create a distribution.
6
7 To do this add the extra paths to the ``develop`` key in the ``[buildout]``
8-section of ``buildout.cfg"::
9+section of ``buildout.cfg``::
10
11 [buildout]
12 develop = .
13
14=== modified file 'doc/chameleon.txt'
15--- doc/chameleon.txt 2009-05-27 22:32:01 +0000
16+++ doc/chameleon.txt 2011-02-16 14:43:33 +0000
17@@ -1,7 +1,7 @@
18 Running Launchpad with Chameleon Template Engine
19 ================================================
20
21-- Need to pull the following dependencies into ``sourcecode``::
22+- Need to pull the following dependencies into ``sourcecode``:
23
24 - lp:sourcecodegen/trunk
25 - lp:chameleon.core/trunk
26@@ -14,7 +14,8 @@
27 ``z3c.pt`` and use ``zope.pagetemplate`` instead. Yes, it's that
28 simple. This is possible thanks to ``z3c.ptcompat``.
29
30-- Other useful environment options for ``z3c.pt``::
31+
32+Other useful environment options for ``z3c.pt``::
33
34 # in debug-mode, templates on disk are reloaded if they're modified
35 CHAMELEON_DEBUG (default: false)
36
37=== added file 'doc/historical.txt'
38--- doc/historical.txt 1970-01-01 00:00:00 +0000
39+++ doc/historical.txt 2011-02-16 14:43:33 +0000
40@@ -0,0 +1,16 @@
41+================================
42+Documents of historical interest
43+================================
44+
45+The following documents don't really represent current thinking or development
46+practices, but are useful to have around to get a sense of where we've been
47+and how we've progressed.
48+
49+Contents:
50+
51+.. toctree::
52+ :maxdepth: 1
53+
54+ chameleon
55+ malone
56+ webapp-process
57
58=== modified file 'doc/index.txt'
59--- doc/index.txt 2011-02-03 16:06:59 +0000
60+++ doc/index.txt 2011-02-16 14:43:33 +0000
61@@ -3,17 +3,47 @@
62 You can adapt this file completely to your liking, but it should at least
63 contain the root `toctree` directive.
64
65+=================================
66 Launchpad developer documentation
67 =================================
68
69-Contents:
70-
71-.. toctree::
72- :maxdepth: 1
73-
74- README <readme>
75- Launchpad Vision <vision>
76- Launchpad Values <values>
77+Welcome to the Launchpad developer documentation. This documentation is for
78+people who want to hack on Launchpad.
79+
80+Overview
81+========
82+
83+.. toctree::
84+ :maxdepth: 1
85+
86+ readme
87+ vision
88+ values
89+
90+Technical
91+=========
92+
93+.. toctree::
94+ :maxdepth: 1
95+
96+ buildout
97+
98+Possibly out-of-date
99+--------------------
100+
101+.. toctree::
102+ :maxdepth: 1
103+
104+ security
105+ email
106+
107+Other
108+=====
109+
110+.. toctree::
111+ :maxdepth: 1
112+
113+ historical
114
115
116 Indices and tables
117
118=== modified file 'doc/malone.txt'
119--- doc/malone.txt 2007-10-31 19:03:15 +0000
120+++ doc/malone.txt 2011-02-16 14:43:33 +0000
121@@ -1,3 +1,6 @@
122+============
123+About Malone
124+============
125
126 The world has many excellent bug tracking tools already. It would not make
127 sense to create another bugtracker unless the vision behind that software
128@@ -6,6 +9,7 @@
129 do for the open source community.
130
131 The Vision behind Malone
132+========================
133
134 Malone is a unified bug tracker for the entire open source world. It is
135 designed to allow the whole open source community to collaborate on software
136@@ -15,15 +19,16 @@
137 specific software defect.
138
139 Upstream and Distributions
140+==========================
141
142 A unique feature of Malone is that it understands the structure of the open
143-source community:
144+source community::
145
146 Software is developed by individuals or groups with a common interest in a
147 specific problem. We call this group "upstream". That software is
148 distributed in its pristine state ("tarballs", usually) and is usually
149 designed to be compiled and run on a variety of platforms.
150-
151+
152 However, most people who use that software will not get it directly from
153 upstream, build it and install it locally. They will install a package
154 that has already been prepared for the specific platform they are running
155@@ -46,6 +51,7 @@
156 information very prominently.
157
158 Watches
159+=======
160
161 It's unlikely that the whole world will shift to Malone. Many larger
162 projects have their own bug tracking tools (Bugzilla, Sourceforge and
163@@ -61,6 +67,7 @@
164 would create a BugWatch in the Malone bug pointing at that upstream bug.
165
166 Email Integration
167+=================
168
169 It's important that Malone be usable entirely in email. Many open source
170 developers use their email to track work that needs to be done. So all of
171@@ -69,6 +76,7 @@
172 reports of bugs on a product or distrbution.
173
174 Distribution Bugs
175+=================
176
177 Malone is designed to track bugs upstream, and in distributions. The
178 requirements for a distribution bugtracker are somewhat specialised. A
179@@ -83,6 +91,7 @@
180 also the precise binary package that manifests the bug.
181
182 Milestones and DistroSeries
183+===========================
184
185 In addition, it's important to be able to know which bugs need to be fix for
186 a given release of the distribution, or a given milestone upstream. Malone
187@@ -91,6 +100,7 @@
188 making towards a release.
189
190 Version Tracking
191+================
192
193 One very difficult problem faced by support teams in the open source world
194 is that users may not all be running the latest version of a piece of code.
195@@ -98,23 +108,24 @@
196 whether a bug is found in a particular version of a package or not.
197
198 Future
199-
200- 1. Bazaar Integration
201- Malone is part of Launchpad, a web based portal for open source
202- developers. Another component of that portal is the Bazaar, a repository
203- of data and metadata about code stored in the Bazaar revision control
204- system. We hope that Bazaar will be embraced by the open source world,
205- as it solves a number of problems with traditional centralised revision
206- control systems and is again designed to support distributed
207- disconnected operation.
208-
209- Once more people start keeping their code in Bazaar, it should become
210- possible to streamline the cooperation process even further. For
211- example, if the fix for a particular Malone bug can be found in a Bazaar
212- changeset, then it should be possible for upstream and other
213- distributions to merge in that fix to their codebase automatically and
214- easily. The integration could even be bidirectional - once a fix had been
215- merged in, Bazaar could possibly detect that and mark the bug fixed in
216- that codebase automatically.
217+======
218+
219+Bazaar Integration
220+------------------
221+
222+Malone is part of Launchpad, a web based portal for open source
223+developers. Another component of that portal is the Bazaar, a repository of
224+data and metadata about code stored in the Bazaar revision control system. We
225+hope that Bazaar will be embraced by the open source world, as it solves a
226+number of problems with traditional centralised revision control systems and
227+is again designed to support distributed disconnected operation.
228+
229+Once more people start keeping their code in Bazaar, it should become possible
230+to streamline the cooperation process even further. For example, if the fix
231+for a particular Malone bug can be found in a Bazaar changeset, then it should
232+be possible for upstream and other distributions to merge in that fix to their
233+codebase automatically and easily. The integration could even be
234+bidirectional - once a fix had been merged in, Bazaar could possibly detect
235+that and mark the bug fixed in that codebase automatically.
236
237
238
239=== modified file 'doc/security.txt'
240--- doc/security.txt 2011-02-04 16:53:06 +0000
241+++ doc/security.txt 2011-02-16 14:43:33 +0000
242@@ -38,7 +38,7 @@
243
244 1. Define the adapter in lib/canonical/launchpad/security.py. Here's a simple
245 example of an adapter that authorizes only an object owner for the
246-launchpad.Edit permission on objects that implement the IHasOwner interface:
247+launchpad.Edit permission on objects that implement the IHasOwner interface::
248
249 class EditByOwner(AuthorizationBase):
250 permission = 'launchpad.Edit'
251@@ -54,7 +54,7 @@
252
253 2. Declare the permission on a given interface in a zcml file. So, for the
254 above adapter, here's how it's hooked up to IProduct, where IProduct is
255-protected with the launchpad.Edit permission:
256+protected with the launchpad.Edit permission::
257
258 <class
259 class="lp.registry.model.product.Product">
260
261=== modified file 'doc/webapp-process.txt'
262--- doc/webapp-process.txt 2010-02-17 11:13:06 +0000
263+++ doc/webapp-process.txt 2011-02-16 14:43:33 +0000
264@@ -194,7 +194,7 @@
265
266 We need to know what types of things are at a particular URL. Here's an
267 example of a typical URL in a web application. This time, I've included
268-the "rosetta" path segment at the root.
269+the "rosetta" path segment at the root::
270
271 /rosetta/projects/$PACKAGENAME/teams/$TEAM/add-member.html
272 | | | | | |