Bazaar

Merge lp:~ian-clatworthy/bzr/sphinx-only into lp:bzr

  1. sphinx-only
  2. Merge into bzr.dev
Proposed by Ian Clatworthy
Status: Work in progress
Proposed branch: lp:~ian-clatworthy/bzr/sphinx-only
Merge into: lp:bzr
Diff against target: 162 lines (+5/-140)
1 file modified
Makefile (+5/-140)
To merge this branch: bzr merge lp:~ian-clatworthy/bzr/sphinx-only
Reviewer Review Type Date Requested Status
Andrew Bennetts Approve
Review via email: mp+26011@code.launchpad.net

Commit message

Drop support for generating docs via docutils - Sphinx only now.

Description of the change

This patch removes support for generating docs via docutils. Once this lands, Sphinx is required for generating docs.

As well as greatly simplifying the Makefile, moving to a single system for doc generation removes numerous bugs, e.g. it makes PDF generation of the User Reference possible.

To post a comment you must log in.
Revision history for this message
Andrew Bennetts (spiv) wrote :

Hooray for simplicity!

Looks good to me.

  review approve
  merge approved

review: Approve
Reply
Revision history for this message
Robert Collins (lifeless) wrote :

sent to pqm by email

Reply
Revision history for this message
Robert Collins (lifeless) wrote :

Missing deps on PQM; I'm not sure what packages are needed to file an RT. Ian, could you please advise?

Reply
Revision history for this message
Martin Pool (mbp) wrote :

We had a list thread about this:

https://lists.ubuntu.com/archives/bazaar/2010q2/068822.html

Summary:

 * everyone likes simplicity
 * sphinx is not packaged in Hardy, which is what the pqm jail currently runs
 * we'll try backporting sphinx
 * if that fails, we'll ask for the chroot to be upgraded and we'll test 2.4 in babune

Until then, this is blocked.

Reply

Unmerged revisions

5256. By Ian Clatworthy

Drop support for generating docs via docutils - Sphinx only now

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== modified file 'Makefile'
--- Makefile 2010-04-06 06:59:03 +0000
+++ Makefile 2010-05-26 04:32:25 +0000
@@ -81,14 +81,11 @@
8181
82### Documentation ###82### Documentation ###
8383
84# Default to plain documentation for maximum backwards compatibility.84docs: docs-sphinx
85# (Post 2.0, the defaults will most likely be Sphinx-style instead.)85
8686clean-docs: clean-sphinx
87docs: docs-plain87
8888html-docs: html-sphinx
89clean-docs: clean-plain
90
91html-docs: html-plain
9289
9390
94### Man-page Documentation ###91### Man-page Documentation ###
@@ -192,138 +189,6 @@
192 $(PYTHON) tools/package_docs.py doc/developers $(DOC_WEBSITE_BUILD)189 $(PYTHON) tools/package_docs.py doc/developers $(DOC_WEBSITE_BUILD)
193190
194191
195### Plain Documentation ###
196
197# While Sphinx is the preferred tool for building documentation, we still
198# support our "plain" html documentation so that Sphinx is not a hard
199# dependency for packagers on older platforms.
200
201rst2html = $(PYTHON) tools/rst2html.py --link-stylesheet --footnote-references=superscript --halt=warning
202
203# translate txt docs to html
204derived_txt_files = \
205 doc/en/release-notes/NEWS.txt
206txt_all = \
207 doc/en/tutorials/tutorial.txt \
208 doc/en/tutorials/using_bazaar_with_launchpad.txt \
209 doc/en/tutorials/centralized_workflow.txt \
210 $(wildcard doc/es/tutorials/*.txt) \
211 $(wildcard doc/ru/tutorials/*.txt) \
212 doc/ja/tutorials/tutorial.txt \
213 doc/ja/tutorials/using_bazaar_with_launchpad.txt \
214 doc/ja/tutorials/centralized_workflow.txt \
215 $(wildcard doc/*/mini-tutorial/index.txt) \
216 $(wildcard doc/*/user-guide/index-plain.txt) \
217 doc/en/admin-guide/index-plain.txt \
218 $(wildcard doc/es/guia-usario/*.txt) \
219 $(derived_txt_files) \
220 doc/en/upgrade-guide/index.txt \
221 doc/index.txt \
222 $(wildcard doc/index.*.txt)
223txt_nohtml = \
224 doc/en/user-guide/index.txt \
225 doc/es/user-guide/index.txt \
226 doc/ja/user-guide/index.txt \
227 doc/ru/user-guide/index.txt \
228 doc/en/admin-guide/index.txt
229txt_files = $(filter-out $(txt_nohtml), $(txt_all))
230htm_files = $(patsubst %.txt, %.html, $(txt_files))
231
232non_txt_files = \
233 doc/default.css \
234 $(wildcard doc/*/bzr-en-quick-reference.svg) \
235 $(wildcard doc/*/bzr-en-quick-reference.png) \
236 $(wildcard doc/*/bzr-en-quick-reference.pdf) \
237 $(wildcard doc/*/bzr-es-quick-reference.svg) \
238 $(wildcard doc/*/bzr-es-quick-reference.png) \
239 $(wildcard doc/*/bzr-es-quick-reference.pdf) \
240 $(wildcard doc/*/bzr-ru-quick-reference.svg) \
241 $(wildcard doc/*/bzr-ru-quick-reference.png) \
242 $(wildcard doc/*/bzr-ru-quick-reference.pdf) \
243 $(wildcard doc/*/user-guide/images/*.png)
244
245# doc/developers/*.txt files that should *not* be individually
246# converted to HTML
247dev_txt_nohtml = \
248 doc/developers/add.txt \
249 doc/developers/annotate.txt \
250 doc/developers/bundle-creation.txt \
251 doc/developers/commit.txt \
252 doc/developers/diff.txt \
253 doc/developers/directory-fingerprints.txt \
254 doc/developers/gc.txt \
255 doc/developers/implementation-notes.txt \
256 doc/developers/incremental-push-pull.txt \
257 doc/developers/index.txt \
258 doc/developers/initial-push-pull.txt \
259 doc/developers/merge-scaling.txt \
260 doc/developers/miscellaneous-notes.txt \
261 doc/developers/missing.txt \
262 doc/developers/performance-roadmap-rationale.txt \
263 doc/developers/performance-use-case-analysis.txt \
264 doc/developers/planned-change-integration.txt \
265 doc/developers/planned-performance-changes.txt \
266 doc/developers/plans.txt \
267 doc/developers/process.txt \
268 doc/developers/revert.txt \
269 doc/developers/specifications.txt \
270 doc/developers/status.txt \
271 doc/developers/uncommit.txt
272
273dev_txt_all = $(wildcard $(addsuffix /*.txt, doc/developers))
274dev_txt_files = $(filter-out $(dev_txt_nohtml), $(dev_txt_all))
275dev_htm_files = $(patsubst %.txt, %.html, $(dev_txt_files))
276
277doc/en/user-guide/index-plain.html: $(wildcard $(addsuffix /*.txt, doc/en/user-guide))
278 $(rst2html) --stylesheet=../../default.css $(dir $@)index-plain.txt $@
279
280#doc/es/user-guide/index.html: $(wildcard $(addsuffix /*.txt, doc/es/user-guide))
281# $(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
282#
283#doc/ru/user-guide/index.html: $(wildcard $(addsuffix /*.txt, doc/ru/user-guide))
284# $(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
285#
286doc/en/admin-guide/index-plain.html: $(wildcard $(addsuffix /*.txt, doc/en/admin-guide))
287 $(rst2html) --stylesheet=../../default.css $(dir $@)index-plain.txt $@
288
289doc/developers/%.html: doc/developers/%.txt
290 $(rst2html) --stylesheet=../default.css $< $@
291
292doc/index.html: doc/index.txt
293 $(rst2html) --stylesheet=default.css $< $@
294
295doc/index.%.html: doc/index.%.txt
296 $(rst2html) --stylesheet=default.css $< $@
297
298%.html: %.txt
299 $(rst2html) --stylesheet=../../default.css $< $@
300
301doc/en/release-notes/NEWS.txt: NEWS
302 $(PYTHON) -c "import shutil; shutil.copyfile('$<', '$@')"
303
304upgrade_guide_dependencies = $(wildcard $(addsuffix /*.txt, doc/en/upgrade-guide))
305
306doc/en/upgrade-guide/index.html: $(upgrade_guide_dependencies)
307 $(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
308
309derived_web_docs = $(htm_files) $(dev_htm_files)
310WEB_DOCS = $(derived_web_docs) $(non_txt_files)
311ALL_DOCS = $(derived_web_docs) $(MAN_PAGES)
312
313# the main target to build all the docs
314docs-plain: $(ALL_DOCS)
315
316# produce a tree containing just the final docs, ready for uploading to the web
317HTMLDIR = html_docs
318html-plain: docs-plain
319 $(PYTHON) tools/win32/ostools.py copytree $(WEB_DOCS) $(HTMLDIR)
320
321# clean produced docs
322clean-plain:
323 $(PYTHON) tools/win32/ostools.py remove $(ALL_DOCS) \
324 $(HTMLDIR) $(derived_txt_files)
325
326
327### Miscellaneous Documentation Targets ###192### Miscellaneous Documentation Targets ###
328193
329# build a png of our performance task list194# build a png of our performance task list