Chris Jerdonek committed 157066a Draft

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.

  • Participants
  • Parent commits a566e3b

Comments (0)

Files changed (1)

 :ref:`CPython Mercurial repository <setup>`.
 .. _reStructuredText:
-.. _docutils:
-.. _Sphinx:
 .. note::
 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
+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.
 where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
 the make targets above).
+.. _docutils:
+.. _Jinja:
+.. _Pygments:
+.. _Sphinx: