Doc: do not rely on checked-out Sphinx toolchain from svn.python.org anymore

Nowadays it is likely that people will have Sphinx installed,
and if not, they will know how to install it.

This also simplifies life a lot for distribution packagers,
who typically do not want the doc build process to connect
to external web resources.

Author: birkenfeld

.hgignore

@@ -24,11 +24,6 @@ python-config.py$
 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
 Misc/python-config.sh$
 Modules/Setup$

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      =
@@ -21,7 +21,6 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
 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 "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@@ -37,30 +36,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.2/sphinx tools/sphinx; \
-	fi
-	@if [ ! -d tools/docutils ]; then \
-	  echo "Checking out Docutils..."; \
-	  svn checkout $(SVNROOT)/external/docutils-0.11/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.6/pygments tools/pygments; \
-	fi
-
-update: clean checkout
-
 build: checkout
-	mkdir -p build/$(BUILDER) build/doctrees
-	$(PYTHON) tools/sphinx-build.py $(ALLSPHINXOPTS)
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 
 html: BUILDER = html
@@ -120,10 +97,6 @@ htmlview: 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

Doc/conf.py

@@ -61,6 +61,8 @@
 # By default, highlight as Python 3.
 highlight_language = 'python3'
 
+needs_sphinx = '1.1'
+
 
 # Options for HTML output
 # -----------------------

Doc/make.bat

@@ -1,7 +1,6 @@
 @@echo off
 setlocal
 
-set SVNROOT=http://svn.python.org/projects
 if "%PYTHON%" EQU "" set PYTHON=py -2
 if "%HTMLHELP%" EQU "" set HTMLHELP=%ProgramFiles%\HTML Help Workshop\hhc.exe
 if "%DISTVERSION%" EQU "" for /f "usebackq" %%v in (`%PYTHON% tools/sphinxext/patchlevel.py`) do set DISTVERSION=%%v
@@ -14,15 +13,11 @@ 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
 
 :help
 set this=%~n0
 echo HELP
 echo.
-echo %this% checkout
-echo %this% update
 echo %this% html
 echo %this% htmlhelp
 echo %this% latex
@@ -33,20 +28,6 @@ echo %this% changes
 echo.
 goto end
 
-:checkout
-svn co %SVNROOT%/external/Sphinx-1.2/sphinx tools/sphinx
-svn co %SVNROOT%/external/docutils-0.11/docutils tools/docutils
-svn co %SVNROOT%/external/Jinja-2.3.1/jinja2 tools/jinja2
-svn co %SVNROOT%/external/Pygments-1.6/pygments tools/pygments
-goto end
-
-:update
-svn update tools/sphinx
-svn update tools/docutils
-svn update tools/jinja2
-svn update tools/pygments
-goto end
-
 :build
 if not exist build mkdir build
 if not exist build\%1 mkdir build\%1

Doc/tools/sphinxext/pyspecific.py

@@ -16,6 +16,7 @@
 
 import sphinx
 from sphinx.util.nodes import split_explicit_title
+from sphinx.util.compat import Directive
 from sphinx.writers.html import HTMLTranslator
 from sphinx.writers.latex import LaTeXTranslator
 from sphinx.locale import versionlabels
@@ -27,7 +28,9 @@
     Body.enum.converters['lowerroman'] = \
     Body.enum.converters['upperroman'] = lambda x: None
 
-if sphinx.__version__[:3] < '1.2':
+SPHINX11 = sphinx.__version__[:3] < '1.2'
+
+if SPHINX11:
     # monkey-patch HTML translator to give versionmodified paragraphs a class
     def new_visit_versionmodified(self, node):
         self.body.append(self.starttag(node, 'p', CLASS=node['type']))
@@ -88,8 +91,6 @@ def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
 
 # Support for marking up implementation details
 
-from sphinx.util.compat import Directive
-
 class ImplementationDetail(Directive):
 
     has_content = True
@@ -142,10 +143,6 @@ def run(self):
 
 # Support for documenting version of removal in deprecations
 
-from sphinx.locale import versionlabels
-from sphinx.util.compat import Directive
-
-
 class DeprecatedRemoved(Directive):
     has_content = True
     required_arguments = 2
@@ -171,23 +168,26 @@ def run(self):
             messages = []
         if self.content:
             self.state.nested_parse(self.content, self.content_offset, node)
-        if len(node):
             if isinstance(node[0], nodes.paragraph) and node[0].rawsource:
                 content = nodes.inline(node[0].rawsource, translatable=True)
                 content.source = node[0].source
                 content.line = node[0].line
                 content += node[0].children
                 node[0].replace_self(nodes.paragraph('', '', content))
-            node[0].insert(0, nodes.inline('', '%s: ' % text,
-                                           classes=['versionmodified']))
-        else:
+            if not SPHINX11:
+                node[0].insert(0, nodes.inline('', '%s: ' % text,
+                                               classes=['versionmodified']))
+        elif not SPHINX11:
             para = nodes.paragraph('', '',
                 nodes.inline('', '%s.' % text, classes=['versionmodified']))
             node.append(para)
         env = self.state.document.settings.env
         env.note_versionchange('deprecated', version[0], node, self.lineno)
         return [node] + messages
 
+# for Sphinx < 1.2
+versionlabels['deprecated-removed'] = DeprecatedRemoved._label
+
 
 # Support for including Misc/NEWS