[Python-checkins] devguide: Improve and make more concise the "Building the documentation" section.

Fri Jan 11 08:30:50 CET 2013

http://hg.python.org/devguide/rev/157066a204ab
changeset: 587:157066a204ab
user: Chris Jerdonek <chris.jerdonek at gmail.com>
date: Thu Jan 10 23:29:47 2013 -0800
summary:
 Improve and make more concise the "Building the documentation" section.
A couple of the changes include adding hyperlinks for each toolset component
and moving the viewing instructions outside of the "Using make" section.
files:
 documenting.rst | 34 +++++++++++++++++++---------------
 1 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/documenting.rst b/documenting.rst
--- a/documenting.rst
+++ b/documenting.rst
@@ -18,8 +18,6 @@
 :ref:`CPython Mercurial repository <setup>`.
 
 .. _reStructuredText: http://docutils.sf.net/rst.html
-.. _docutils: http://docutils.sf.net/
-.. _Sphinx: http://sphinx-doc.org/
 
 .. note::
 
@@ -1629,29 +1627,30 @@
 Building the documentation
 ==========================
 
-You need to have Python 2.4 or higher installed; the toolset used to build the
-docs is written in Python. It is called *Sphinx*, it is not included in this
-tree, but maintained separately. Also needed are the docutils, supplying the
-base markup that Sphinx uses, Jinja, a templating engine, and optionally
-Pygments, a code highlighter.
+You need to have Python 2.4 or higher installed. The toolset used to build
+the docs is written in Python and is called Sphinx_. Sphinx is maintained
+separately and is not included in this tree. Also needed are docutils_,
+supplying the base markup that Sphinx uses; Jinja_, a templating engine; and
+optionally Pygments_, a code highlighter.
+
+To build the documentation, follow the instructions from one of the sections
+below. You can view the documentation after building the HTML by pointing
+a browser at the file :file:`Doc/build/html/index.html`.
 
 
 Using make
 ----------
 
-Luckily, a Makefile has been prepared so that on Unix, provided you have
-installed Python and Subversion, you can just go to your :ref:`clone of the
-CPython Mercurial repository <setup>` and run ::
+On Unix, if you have Subversion installed, run the following from the root of
+your :ref:`repository clone <checkout>`::
 
 cd Doc
 make html
 
-to check out the necessary toolset in the :file:`Doc/tools/` subdirectory and
-build the HTML output files. To view the generated HTML, point your favorite
-browser at the top-level index :file:`Doc/build/html/index.html` after running
-:command:`make`.
+This checks out the needed toolset in the :file:`Doc/tools/` directory and
+builds the output as HTML.
 
-Available make targets are:
+Available :command:`make` targets are:
 
 * "html", which builds standalone HTML files for offline viewing.
 
@@ -1721,3 +1720,8 @@
 
 where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
 the make targets above).
+
+.. _docutils: http://docutils.sourceforge.net/
+.. _Jinja: http://jinja.pocoo.org/
+.. _Pygments: http://pygments.org/
+.. _Sphinx: http://sphinx-doc.org/
-- 
Repository URL: http://hg.python.org/devguide
