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.

diff --git a/Doc/README.txt b/Doc/README.txt
index b343aca2ee7c63fdc44ad2038cefb4f7fd921759..7fac730e55af87b3bcb2ec98e73aedcdeecdcb77 100644 (file)
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -7,14 +7,13 @@ available at http://docs.python.org/download/.
 
 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 @@ to check out the necessary toolset in the `tools/` subdirectory and build the
 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 @@ Available make targets are:
    `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 ::
-
-   svn co http://svn.python.org/projects/external/Sphinx-0.6.7/sphinx tools/sphinx
-
-or by installing it from PyPI.
-
-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.
-
+Install the Sphinx package and its dependencies from PyPI.
 
-Then, make an output directory, e.g. under `build/`, and run ::
+Then, from the ``Docs`` directory, run ::
 
-   python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
+   sphinx-build -b<builder> . build/<builder>
 
-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
index a0bd7fa0db08ed8adcdcb46d06c1b568ce8382ff..d3fe7026b1311bc5bcf13d237f042089f9286fa8 100644 (file)
--- a/Doc/tools/sphinx-build.py
+++ b/Doc/tools/sphinx-build.py
@@ -15,13 +15,13 @@ warnings.filterwarnings('ignore', category=UserWarning, module='jinja2')
 
 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