Closes #17386: Merge with 3.4
This commit is contained in:
Zachary Ware
commit
e83ce4b90f
|
|
@ -22,6 +22,7 @@ help:
|
|||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " clean to remove build files"
|
||||
@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"
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ 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/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
|
||||
developers guide <http://docs.python.org/devguide/documenting.html>.
|
||||
|
||||
|
|
@ -26,8 +26,7 @@ Sphinx, you can just run ::
|
|||
|
||||
make html
|
||||
|
||||
to 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.
|
||||
|
|
@ -35,18 +34,29 @@ On Windows, we try to emulate the Makefile as closely as possible with a
|
|||
To use a Python interpreter that's not called ``python``, use the standard
|
||||
way to set Makefile variables, using e.g. ::
|
||||
|
||||
make html PYTHON=/usr/bin/python2.5
|
||||
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.
|
||||
|
|
@ -75,6 +85,13 @@ Available make targets are:
|
|||
* "suspicious", which checks the parsed markup for text that looks like
|
||||
malformed and thus unconverted reST.
|
||||
|
||||
* "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
|
||||
------------
|
||||
|
|
|
|||
121
Doc/make.bat
121
Doc/make.bat
|
|
@ -1,40 +1,115 @@
|
|||
@@echo off
|
||||
@echo off
|
||||
setlocal
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
set this=%~n0
|
||||
|
||||
if "%SPHINXBUILD%" EQU "" set SPHINXBUILD=sphinx-build
|
||||
if "%PYTHON%" EQU "" set PYTHON=py
|
||||
if "%HTMLHELP%" EQU "" set HTMLHELP=%ProgramFiles%\HTML Help Workshop\hhc.exe
|
||||
|
||||
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 "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% 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.
|
||||
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 %SPHINXBUILD% -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" (
|
||||
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
|
||||
|
|
|
|||
|
|
@ -340,6 +340,9 @@ C API
|
|||
Documentation
|
||||
-------------
|
||||
|
||||
- Issue #17386: Expanded functionality of the ``Doc/make.bat`` script to make
|
||||
it much more comparable to ``Doc/Makefile``.
|
||||
|
||||
- Issue #21312: Update the thread_foobar.h template file to include newer
|
||||
threading APIs. Patch by Jack McCracken.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue