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.
diff --git a/.hgignore b/.hgignore
index e30ec86..d6c6c73 100644
--- a/.hgignore
+++ b/.hgignore
@@ -21,11 +21,6 @@
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
diff --git a/Doc/Makefile b/Doc/Makefile
index 07bf9b2..43dd804 100644
--- a/Doc/Makefile
+++ b/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 @@
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 @@
@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: 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 @@
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 @@
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 @@
# 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-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
diff --git a/Doc/README.txt b/Doc/README.txt
index b8ff47f..fed1f74 100644
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -3,54 +3,69 @@
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 @@
* "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 @@
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>
diff --git a/Doc/make.bat b/Doc/make.bat
index d3f01b5..b26826e 100644
--- a/Doc/make.bat
+++ b/Doc/make.bat
@@ -1,58 +1,124 @@
-@@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 %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.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.
-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
-goto end
-
-:update
-svn update tools/sphinx
-svn update tools/docutils
-svn update tools/jinja2
-svn update tools/pygments
+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 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
+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
+
+: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
+
+:check
+cmd /C %PYTHON% tools\rstlint.py -i tools
+goto end
+
+:serve
+cmd /C %PYTHON% ..\Tools\scripts\serve.py %BUILDDIR%\html
goto end
:end
+popd
diff --git a/Misc/NEWS b/Misc/NEWS
index ef96a39..e50de99 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -158,6 +158,9 @@
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.