remove automatic svn checkout of sphinx and its deps from Doc/Makefile

Users are now required to install Sphinx themselves as is already the case with
the Python 3 branch.

.hgignore

@@ -21,11 +21,6 @@ python.exe$
 reflog.txt$
 tags$
 Lib/plat-mac/errors.rsrc.df.rsrc
-Doc/tools/sphinx/
-Doc/tools/docutils/
-Doc/tools/jinja/
-Doc/tools/jinja2/
-Doc/tools/pygments/
 Misc/python.pc
 Modules/Setup$
 Modules/Setup.config

Doc/Makefile

@@ -5,7 +5,7 @@
 
 # You can set these variables from the command line.
 PYTHON       = python
-SVNROOT      = http://svn.python.org/projects
+SPHINXBUILD  = sphinx-build
 SPHINXOPTS   =
 PAPER        =
 SOURCES      =
@@ -14,18 +14,19 @@ DISTVERSION  = $(shell $(PYTHON) tools/sphinxext/patchlevel.py)
 ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
                 $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
 
-.PHONY: help checkout update build html htmlhelp latex text changes linkcheck \
+.PHONY: help build html htmlhelp latex text changes linkcheck \
 	suspicious coverage doctest pydoc-topics htmlview clean dist check serve \
 	autobuild-dev autobuild-stable
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  clean      to remove build files"
-	@echo "  update     to update build tools"
 	@echo "  html       to make standalone HTML files"
+	@echo "  htmlview   to open the index page built by the html target in your browser"
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  text       to make plain text files"
+	@echo "  epub       to make EPUB files"
 	@echo "  changes    to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  coverage   to check documentation coverage for library and C API"
@@ -36,30 +37,8 @@ help:
 	@echo "  check      to run a check for frequent markup errors"
 	@echo "  serve      to serve the documentation on the localhost (8000)"
 
-# Note: if you update versions here, do the same in make.bat and README.txt
-checkout:
-	@if [ ! -d tools/sphinx ]; then \
-	  echo "Checking out Sphinx..."; \
-	  svn checkout $(SVNROOT)/external/Sphinx-1.0.7/sphinx tools/sphinx; \
-	fi
-	@if [ ! -d tools/docutils ]; then \
-	  echo "Checking out Docutils..."; \
-	  svn checkout $(SVNROOT)/external/docutils-0.6/docutils tools/docutils; \
-	fi
-	@if [ ! -d tools/jinja2 ]; then \
-	  echo "Checking out Jinja..."; \
-	  svn checkout $(SVNROOT)/external/Jinja-2.3.1/jinja2 tools/jinja2; \
-	fi
-	@if [ ! -d tools/pygments ]; then \
-	  echo "Checking out Pygments..."; \
-	  svn checkout $(SVNROOT)/external/Pygments-1.3.1/pygments tools/pygments; \
-	fi
-
-update: clean checkout
-
-build: checkout
-	mkdir -p build/$(BUILDER) build/doctrees
-	$(PYTHON) tools/sphinx-build.py $(ALLSPHINXOPTS)
+build:
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 
 html: BUILDER = html
@@ -81,6 +60,10 @@ text: BUILDER = text
 text: build
 	@echo "Build finished; the text files are in build/text."
 
+epub: BUILDER = epub
+epub: build
+	@echo "Build finished; the epub files are in build/epub."
+
 changes: BUILDER = changes
 changes: build
 	@echo "The overview file is in build/changes."
@@ -114,17 +97,13 @@ doctest:
 pydoc-topics: BUILDER = pydoc-topics
 pydoc-topics: build
 	@echo "Building finished; now copy build/pydoc-topics/topics.py" \
-	      "to Lib/pydoc_data/topics.py"
+	      "to ../Lib/pydoc_data/topics.py"
 
 htmlview: html
 	 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
 
 clean:
 	-rm -rf build/*
-	-rm -rf tools/sphinx
-	-rm -rf tools/pygments
-	-rm -rf tools/jinja2
-	-rm -rf tools/docutils
 
 dist:
 	rm -rf dist
@@ -164,6 +143,11 @@ dist:
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
 
+	# copy the epub build
+	rm -rf build/epub
+	make epub
+	cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
+
 check:
 	$(PYTHON) tools/rstlint.py -i tools
 
@@ -174,7 +158,6 @@ serve:
 
 # for development releases: always build
 autobuild-dev:
-	make update
 	make dist SPHINXOPTS='-A daily=1 -A versionswitcher=1'
 	-make suspicious
 
@@ -182,10 +165,9 @@ autobuild-dev:
 autobuild-html:
 	make html SPHINXOPTS='-A daily=1 -A versionswitcher=1'
 
-# for stable releases: only build if not in pre-release stage (alpha, beta)
-# release candidate downloads are okay, since the stable tree can be in that stage
+# for stable releases: only build if not in pre-release stage (alpha, beta, rc)
 autobuild-stable:
-	@case $(DISTVERSION) in *[ab]*) \
+	@case $(DISTVERSION) in *[abc]*) \
 		echo "Not building; $(DISTVERSION) is not a release version."; \
 		exit 1;; \
 	esac

Doc/README.txt

@@ -3,54 +3,69 @@ Python Documentation README
 
 This directory contains the reStructuredText (reST) sources to the Python
 documentation.  You don't need to build them yourself, prebuilt versions are
-available at https://docs.python.org/2/download.html
+available at <https://docs.python.org/dev/download.html>.
 
-Documentation on the authoring Python documentation, including information about
+Documentation on authoring Python documentation, including information about
 both style and markup, is available in the "Documenting Python" chapter of the
-documentation.
+developers guide <http://docs.python.org/devguide/documenting.html>.
 
 
 Building the docs
 =================
 
-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
-Pygments, a code highlighter.
+You need to have Sphinx <http://sphinx-doc.org/> installed; it is the toolset
+used to build the docs.  It is not included in this tree, but maintained
+separately and available from PyPI <http://pypi.python.org/pypi/Sphinx>.
 
 
 Using make
 ----------
 
-Luckily, a Makefile has been prepared so that on Unix, provided you have
-installed Python and Subversion, you can just run ::
+A Makefile has been prepared so that on Unix, provided you have installed
+Sphinx, you can just run ::
 
    make html
 
-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".
+to build the HTML output files.
 
 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. ::
+
+   make html PYTHON=python3
+
+On Windows, set the PYTHON environment variable instead.
+
+To use a specific sphinx-build (something other than ``sphinx-build``), set
+the SPHINXBUILD variable.
+
 Available make targets are:
 
+ * "clean", which removes all build files.
+
  * "html", which builds standalone HTML files for offline viewing.
 
+ * "htmlview", which re-uses the "html" builder, but then opens the main page
+   in your default web browser.
+
  * "htmlhelp", which builds HTML files and a HTML Help project file usable to
    convert them into a single Compiled HTML (.chm) file -- these are popular
    under Microsoft Windows, but very handy on every platform.
 
-   To create the CHM file, you need to run the Microsoft HTML Help Workshop over
-   the generated project (.hhp) file.
+   To create the CHM file, you need to run the Microsoft HTML Help Workshop
+   over the generated project (.hhp) file.  The make.bat script does this for
+   you on Windows.
 
  * "latex", which builds LaTeX source files as input to "pdflatex" to produce
    PDF documents.
 
  * "text", which builds a plain text file for each source file.
 
+ * "epub", which builds an EPUB document, suitable to be viewed on e-book
+   readers.
+
  * "linkcheck", which checks all external references to see whether they are
    broken, redirected or malformed, and outputs this information to stdout as
    well as a plain-text (.txt) file.
@@ -70,7 +85,12 @@ Available make targets are:
  * "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/`.
+ * "check", which checks for frequent markup errors.
+
+ * "serve", which serves the build/html directory on port 8000.
+
+ * "dist", (Unix only) which creates distributable archives of HTML, text,
+   PDF, and EPUB builds.
 
 
 Without make
@@ -78,7 +98,7 @@ Without make
 
 Install the Sphinx package and its dependencies from PyPI.
 
-Then, from the ``Docs`` directory, run ::
+Then, from the ``Doc`` directory, run ::
 
    sphinx-build -b<builder> . build/<builder>
 

Doc/make.bat

-@@echo off
+@echo off
 setlocal
 
-set SVNROOT=http://svn.python.org/projects
-if "%PYTHON%" EQU "" set PYTHON=..\pcbuild\python
-if "%HTMLHELP%" EQU "" set HTMLHELP=%ProgramFiles%\HTML Help Workshop\hhc.exe
+pushd %~dp0
+
+set this=%~n0
+
+if "%SPHINXBUILD%" EQU "" set SPHINXBUILD=sphinx-build
+if "%PYTHON%" EQU "" set PYTHON=py
+
+if DEFINED ProgramFiles(x86) set _PRGMFLS=%ProgramFiles(x86)%
+if NOT DEFINED ProgramFiles(x86) set _PRGMFLS=%ProgramFiles%
+if "%HTMLHELP%" EQU "" set HTMLHELP=%_PRGMFLS%\HTML Help Workshop\hhc.exe
+
 if "%DISTVERSION%" EQU "" for /f "usebackq" %%v in (`%PYTHON% tools/sphinxext/patchlevel.py`) do set DISTVERSION=%%v
 
+if "%BUILDDIR%" EQU "" set BUILDDIR=build
+
+rem Targets that don't require sphinx-build
 if "%1" EQU "" goto help
-if "%1" EQU "html" goto build
-if "%1" EQU "htmlhelp" goto build
-if "%1" EQU "latex" goto build
-if "%1" EQU "text" goto build
-if "%1" EQU "suspicious" goto build
-if "%1" EQU "linkcheck" goto build
-if "%1" EQU "changes" goto build
-if "%1" EQU "checkout" goto checkout
-if "%1" EQU "update" goto update
+if "%1" EQU "help" goto help
+if "%1" EQU "check" goto check
+if "%1" EQU "serve" goto serve
+if "%1" == "clean" (
+    rmdir /q /s %BUILDDIR%
+    goto end
+)
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+    echo.
+    echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+    echo.installed, then set the SPHINXBUILD environment variable to point
+    echo.to the full path of the 'sphinx-build' executable. Alternatively you
+    echo.may add the Sphinx directory to PATH.
+    echo.
+    echo.If you don't have Sphinx installed, grab it from
+    echo.http://sphinx-doc.org/
+    goto end
+)
+
+rem Targets that do require sphinx-build and have their own label
+if "%1" EQU "htmlview" goto htmlview
+
+rem Everything else
+goto build
 
 :help
-set this=%~n0
-echo HELP
+echo.usage: %this% BUILDER [filename ...]
+echo.
+echo.Call %this% with the desired Sphinx builder as the first argument, e.g.
+echo.``%this% html`` or ``%this% doctest``.  Interesting targets that are
+echo.always available include:
 echo.
-echo %this% checkout
-echo %this% update
-echo %this% html
-echo %this% htmlhelp
-echo %this% latex
-echo %this% text
-echo %this% suspicious
-echo %this% linkcheck
-echo %this% changes
+echo.   Provided by Sphinx:
+echo.      html, htmlhelp, latex, text
+echo.      suspicious, linkcheck, changes, doctest
+echo.   Provided by this script:
+echo.      clean, check, serve, htmlview
 echo.
+echo.All arguments past the first one are passed through to sphinx-build as
+echo.filenames to build or are ignored.  See README.txt in this directory or
+echo.the documentation for your version of Sphinx for more exhaustive lists
+echo.of available targets and descriptions of each.
+echo.
+echo.This script assumes that the SPHINXBUILD environment variable contains
+echo.a legitimate command for calling sphinx-build, or that sphinx-build is
+echo.on your PATH if SPHINXBUILD is not set.  Options for sphinx-build can
+echo.be passed by setting the SPHINXOPTS environment variable.
+goto end
+
+:build
+if NOT "%PAPER%" == "" (
+    set SPHINXOPTS=-D latex_paper_size=%PAPER% %SPHINXOPTS%
+)
+cmd /C %SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . %BUILDDIR%\%*
+
+if "%1" EQU "htmlhelp" (
+    if  not exist "%HTMLHELP%" (
+        echo.
+        echo.The HTML Help Workshop was not found.  Set the HTMLHELP variable
+        echo.to the path to hhc.exe or download and install it from
+        echo.http://msdn.microsoft.com/en-us/library/ms669985
+        rem Set errorlevel to 1 and exit
+        cmd /C exit /b 1
+        goto end
+    )
+    cmd /C "%HTMLHELP%" build\htmlhelp\python%DISTVERSION:.=%.hhp
+    rem hhc.exe seems to always exit with code 1, reset to 0 for less than 2
+    if not errorlevel 2 cmd /C exit /b 0
+)
+
+echo.
+if errorlevel 1 (
+    echo.Build failed (exit code %ERRORLEVEL%^), check for error messages
+    echo.above.  Any output will be found in %BUILDDIR%\%1
+) else (
+    echo.Build succeeded. All output should be in %BUILDDIR%\%1
+)
 goto end
 
-:checkout
-svn co %SVNROOT%/external/Sphinx-1.0.7/sphinx tools/sphinx
-svn co %SVNROOT%/external/docutils-0.6/docutils tools/docutils
-svn co %SVNROOT%/external/Jinja-2.3.1/jinja2 tools/jinja2
-svn co %SVNROOT%/external/Pygments-1.3.1/pygments tools/pygments
+:htmlview
+if NOT "%2" EQU "" (
+    echo.Can't specify filenames to build with htmlview target, ignoring.
+)
+cmd /C %this% html
+
+if EXIST %BUILDDIR%\html\index.html (
+    echo.Opening %BUILDDIR%\html\index.html in the default web browser...
+    start %BUILDDIR%\html\index.html
+)
+
 goto end
 
-:update
-svn update tools/sphinx
-svn update tools/docutils
-svn update tools/jinja2
-svn update tools/pygments
+:check
+cmd /C %PYTHON% tools\rstlint.py -i tools
 goto end
 
-:build
-if not exist build mkdir build
-if not exist build\%1 mkdir build\%1
-if not exist build\doctrees mkdir build\doctrees
-cmd /C %PYTHON% tools\sphinx-build.py -b%1 -dbuild\doctrees . build\%*
-if "%1" EQU "htmlhelp" "%HTMLHELP%" build\htmlhelp\python%DISTVERSION:.=%.hhp
+:serve
+cmd /C %PYTHON% ..\Tools\scripts\serve.py %BUILDDIR%\html
 goto end
 
 :end
+popd

Misc/NEWS

@@ -158,6 +158,9 @@ Tests
 Build
 -----
 
+- The documentation Makefile no longer automatically downloads Sphinx. Users are
+  now required to have Sphinx already installed to build the documentation.
+
 - Issue #21958: Define HAVE_ROUND when building with Visual Studio 2013 and
   above.  Patch by Zachary Turner.