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.
This commit is contained in:
Georg Brandl 2014-02-16 09:46:36 +01:00
parent a3d0ffe2c6
commit f7b2f36f74
5 changed files with 15 additions and 64 deletions

View File

@ -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$

View File

@ -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

View File

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

View File

@ -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

View File

@ -16,6 +16,7 @@ from docutils import nodes, utils
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['loweralpha'] = \
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 @@ class PyDecoratorMethod(PyDecoratorMixin, PyClassmember):
# 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,16 +168,16 @@ class DeprecatedRemoved(Directive):
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)
@ -188,6 +185,9 @@ class DeprecatedRemoved(Directive):
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