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 a16c14ac61d59bd47bae0dc129abd4a93e4af913..a494c89db6aac4f9a6d04882340427cc354ad991 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.
+
 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

diff --git a/Doc/tools/sphinx-build.py b/Doc/tools/sphinx-build.py
index a446dfa8e18cf3c18e79cb0cf5814a2583ff55ac..d3fe7026b1311bc5bcf13d237f042089f9286fa8 100644 (file)
--- a/Doc/tools/sphinx-build.py
+++ b/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``).