[Python-checkins] cpython (2.7): Closes #20090: update Doc/README and the error message in sphinx-build.py to

[georg.brandl]

http://hg.python.org/cpython/rev/0ae254c11921
changeset:   89558:0ae254c11921
branch:      2.7
parent:      89526:16c5d7c289c6
user:        Georg Brandl <georg at python.org>
date:        Mon Mar 10 19:26:57 2014 +0100
summary:
  Closes #20090: update Doc/README and the error message in sphinx-build.py to make
it clear that any Python 3.x is not usable with the checked out Sphinx.

files:
  Doc/README.txt            |  44 +++++++-------------------
  Doc/tools/sphinx-build.py |   8 ++--
  2 files changed, 17 insertions(+), 35 deletions(-)


diff --git a/Doc/README.txt b/Doc/README.txt
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -7,14 +7,13 @@
 
 Documentation on the authoring Python documentation, including information about
 both style and markup, is available in the "Documenting Python" chapter of the
-documentation.  There's also a chapter intended to point out differences to
-those familiar with the previous docs written in LaTeX.
+documentation.
 
 
 Building the docs
 =================
 
-You need to have Python 2.4 or higher installed; the toolset used to build the
+You need to have Python 2 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
@@ -33,6 +32,9 @@
 HTML output files.  To view the generated HTML, point your favorite browser at
 the top-level index `build/html/index.html` after running "make".
 
+On Windows, we try to emulate the Makefile as closely as possible with a
+``make.bat`` file.
+
 Available make targets are:
 
  * "html", which builds standalone HTML files for offline viewing.
@@ -65,43 +67,23 @@
    `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
    keyword help.
 
+ * "suspicious", which checks the parsed markup for text that looks like
+   malformed and thus unconverted reST.
+
 A "make update" updates the Subversion checkouts in `tools/`.
 
 
 Without make
 ------------
 
-You'll need to install the Sphinx package, either by checking it out via ::
+Install the Sphinx package and its dependencies from PyPI.
 
-   svn co http://svn.python.org/projects/external/Sphinx-0.6.7/sphinx tools/sphinx
+Then, from the ``Docs`` directory, run ::
 
-or by installing it from PyPI.
+   sphinx-build -b<builder> . build/<builder>
 
-Then, you need to install Docutils, either by checking it out via ::
-
-   svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
-
-or by installing it from http://docutils.sf.net/.
-
-You also need Jinja2, either by checking it out via ::
-
-   svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
-
-or by installing it from PyPI.
-
-You can optionally also install Pygments, either as a checkout via ::
-
-   svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
-
-or from PyPI at http://pypi.python.org/pypi/Pygments.
-
-
-Then, make an output directory, e.g. under `build/`, and run ::
-
-   python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
-
-where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
-the make targets above).
+where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
+see the make targets above).
 
 
 Contributing
diff --git a/Doc/tools/sphinx-build.py b/Doc/tools/sphinx-build.py
--- a/Doc/tools/sphinx-build.py
+++ b/Doc/tools/sphinx-build.py
@@ -15,13 +15,13 @@
 
 if __name__ == '__main__':
 
-    if sys.version_info[:3] < (2, 4, 0):
-        print >>sys.stderr, """\
-Error: Sphinx needs to be executed with Python 2.4 or newer
+    if sys.version_info[:3] < (2, 4, 0) or sys.version_info[:3] > (3, 0, 0):
+        sys.stderr.write("""\
+Error: Sphinx needs to be executed with Python 2.4 or newer (not 3.x though).
 (If you run this from the Makefile, you can set the PYTHON variable
 to the path of an alternative interpreter executable, e.g.,
 ``make html PYTHON=python2.5``).
-"""
+""")
         sys.exit(1)
 
     from sphinx import main

-- 
Repository URL: http://hg.python.org/cpython