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
1=== modified file 'Makefile'
2--- Makefile 2010-04-06 06:59:03 +0000
3+++ Makefile 2010-05-26 04:32:25 +0000
4@@ -81,14 +81,11 @@
5
6 ### Documentation ###
7
8-# Default to plain documentation for maximum backwards compatibility.
9-# (Post 2.0, the defaults will most likely be Sphinx-style instead.)
10-
11-docs: docs-plain
12-
13-clean-docs: clean-plain
14-
15-html-docs: html-plain
16+docs: docs-sphinx
17+
18+clean-docs: clean-sphinx
19+
20+html-docs: html-sphinx
21
22
23 ### Man-page Documentation ###
24@@ -192,138 +189,6 @@
25 $(PYTHON) tools/package_docs.py doc/developers $(DOC_WEBSITE_BUILD)
26
27
28-### Plain Documentation ###
29-
30-# While Sphinx is the preferred tool for building documentation, we still
31-# support our "plain" html documentation so that Sphinx is not a hard
32-# dependency for packagers on older platforms.
33-
34-rst2html = $(PYTHON) tools/rst2html.py --link-stylesheet --footnote-references=superscript --halt=warning
35-
36-# translate txt docs to html
37-derived_txt_files = \
38- doc/en/release-notes/NEWS.txt
39-txt_all = \
40- doc/en/tutorials/tutorial.txt \
41- doc/en/tutorials/using_bazaar_with_launchpad.txt \
42- doc/en/tutorials/centralized_workflow.txt \
43- $(wildcard doc/es/tutorials/*.txt) \
44- $(wildcard doc/ru/tutorials/*.txt) \
45- doc/ja/tutorials/tutorial.txt \
46- doc/ja/tutorials/using_bazaar_with_launchpad.txt \
47- doc/ja/tutorials/centralized_workflow.txt \
48- $(wildcard doc/*/mini-tutorial/index.txt) \
49- $(wildcard doc/*/user-guide/index-plain.txt) \
50- doc/en/admin-guide/index-plain.txt \
51- $(wildcard doc/es/guia-usario/*.txt) \
52- $(derived_txt_files) \
53- doc/en/upgrade-guide/index.txt \
54- doc/index.txt \
55- $(wildcard doc/index.*.txt)
56-txt_nohtml = \
57- doc/en/user-guide/index.txt \
58- doc/es/user-guide/index.txt \
59- doc/ja/user-guide/index.txt \
60- doc/ru/user-guide/index.txt \
61- doc/en/admin-guide/index.txt
62-txt_files = $(filter-out $(txt_nohtml), $(txt_all))
63-htm_files = $(patsubst %.txt, %.html, $(txt_files))
64-
65-non_txt_files = \
66- doc/default.css \
67- $(wildcard doc/*/bzr-en-quick-reference.svg) \
68- $(wildcard doc/*/bzr-en-quick-reference.png) \
69- $(wildcard doc/*/bzr-en-quick-reference.pdf) \
70- $(wildcard doc/*/bzr-es-quick-reference.svg) \
71- $(wildcard doc/*/bzr-es-quick-reference.png) \
72- $(wildcard doc/*/bzr-es-quick-reference.pdf) \
73- $(wildcard doc/*/bzr-ru-quick-reference.svg) \
74- $(wildcard doc/*/bzr-ru-quick-reference.png) \
75- $(wildcard doc/*/bzr-ru-quick-reference.pdf) \
76- $(wildcard doc/*/user-guide/images/*.png)
77-
78-# doc/developers/*.txt files that should *not* be individually
79-# converted to HTML
80-dev_txt_nohtml = \
81- doc/developers/add.txt \
82- doc/developers/annotate.txt \
83- doc/developers/bundle-creation.txt \
84- doc/developers/commit.txt \
85- doc/developers/diff.txt \
86- doc/developers/directory-fingerprints.txt \
87- doc/developers/gc.txt \
88- doc/developers/implementation-notes.txt \
89- doc/developers/incremental-push-pull.txt \
90- doc/developers/index.txt \
91- doc/developers/initial-push-pull.txt \
92- doc/developers/merge-scaling.txt \
93- doc/developers/miscellaneous-notes.txt \
94- doc/developers/missing.txt \
95- doc/developers/performance-roadmap-rationale.txt \
96- doc/developers/performance-use-case-analysis.txt \
97- doc/developers/planned-change-integration.txt \
98- doc/developers/planned-performance-changes.txt \
99- doc/developers/plans.txt \
100- doc/developers/process.txt \
101- doc/developers/revert.txt \
102- doc/developers/specifications.txt \
103- doc/developers/status.txt \
104- doc/developers/uncommit.txt
105-
106-dev_txt_all = $(wildcard $(addsuffix /*.txt, doc/developers))
107-dev_txt_files = $(filter-out $(dev_txt_nohtml), $(dev_txt_all))
108-dev_htm_files = $(patsubst %.txt, %.html, $(dev_txt_files))
109-
110-doc/en/user-guide/index-plain.html: $(wildcard $(addsuffix /*.txt, doc/en/user-guide))
111- $(rst2html) --stylesheet=../../default.css $(dir $@)index-plain.txt $@
112-
113-#doc/es/user-guide/index.html: $(wildcard $(addsuffix /*.txt, doc/es/user-guide))
114-# $(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
115-#
116-#doc/ru/user-guide/index.html: $(wildcard $(addsuffix /*.txt, doc/ru/user-guide))
117-# $(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
118-#
119-doc/en/admin-guide/index-plain.html: $(wildcard $(addsuffix /*.txt, doc/en/admin-guide))
120- $(rst2html) --stylesheet=../../default.css $(dir $@)index-plain.txt $@
121-
122-doc/developers/%.html: doc/developers/%.txt
123- $(rst2html) --stylesheet=../default.css $< $@
124-
125-doc/index.html: doc/index.txt
126- $(rst2html) --stylesheet=default.css $< $@
127-
128-doc/index.%.html: doc/index.%.txt
129- $(rst2html) --stylesheet=default.css $< $@
130-
131-%.html: %.txt
132- $(rst2html) --stylesheet=../../default.css $< $@
133-
134-doc/en/release-notes/NEWS.txt: NEWS
135- $(PYTHON) -c "import shutil; shutil.copyfile('$<', '$@')"
136-
137-upgrade_guide_dependencies = $(wildcard $(addsuffix /*.txt, doc/en/upgrade-guide))
138-
139-doc/en/upgrade-guide/index.html: $(upgrade_guide_dependencies)
140- $(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
141-
142-derived_web_docs = $(htm_files) $(dev_htm_files)
143-WEB_DOCS = $(derived_web_docs) $(non_txt_files)
144-ALL_DOCS = $(derived_web_docs) $(MAN_PAGES)
145-
146-# the main target to build all the docs
147-docs-plain: $(ALL_DOCS)
148-
149-# produce a tree containing just the final docs, ready for uploading to the web
150-HTMLDIR = html_docs
151-html-plain: docs-plain
152- $(PYTHON) tools/win32/ostools.py copytree $(WEB_DOCS) $(HTMLDIR)
153-
154-# clean produced docs
155-clean-plain:
156- $(PYTHON) tools/win32/ostools.py remove $(ALL_DOCS) \
157- $(HTMLDIR) $(derived_txt_files)
158-
159-
160 ### Miscellaneous Documentation Targets ###
161
162 # build a png of our performance task list