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.

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.
+
 To use a Python interpreter that's not called ``python``, use the standard
 way to set Makefile variables, using e.g. ::
 
@@ -73,43 +75,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-1.0.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

Doc/tools/sphinx-build.py

@@ -17,7 +17,7 @@ if __name__ == '__main__':
 
     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.0 though).
+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``).