diff --git a/Doc/Makefile b/Doc/Makefile --- a/Doc/Makefile +++ b/Doc/Makefile @@ -24,6 +24,7 @@ @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 " htmlview to make HTML files and open a webbrowser to the main page" @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" diff --git a/Doc/README.txt b/Doc/README.txt --- a/Doc/README.txt +++ b/Doc/README.txt @@ -5,7 +5,7 @@ documentation. You don't need to build them yourself, prebuilt versions are available at http://docs.python.org/download/. -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. There's also a chapter intended to point out differences to those familiar with the previous docs written in LaTeX. @@ -24,8 +24,8 @@ Using make ---------- -Luckily, a Makefile has been prepared so that on Unix, provided you have -installed Python and Subversion, you can just run :: +Luckily, a Makefile and a make.bat script have been prepared so that, provided +you have installed Python and Subversion, you can just run :: make html @@ -36,10 +36,18 @@ 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=/usr/bin/python2.7 + +On Windows, you'll need to enclose the variable in quotes, like:: + + make html "PYTHON2=C:\Python27\python.exe" Available make targets are: + * "clean", which removes build files and tools. + + * "update", which makes sure the build tools are up-to-date and ready. + * "html", which builds standalone HTML files for offline viewing. * "htmlhelp", which builds HTML files and a HTML Help project file usable to @@ -47,7 +55,11 @@ 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. + the generated project (.hhp) file. On Windows, make.bat does this for you if + it can, and will warn you if it can't. + + * "htmlview", which builds the HTML files (exactly like ``make html`` does) and + opens a webbrowser to the main page. * "latex", which builds LaTeX source files as input to "pdflatex" to produce PDF documents. @@ -57,23 +69,32 @@ * "epub", which builds an EPUB document, suitable to be viewed on e-book readers. + * "changes", which builds an overview over all versionadded/versionchanged/ + deprecated items in the current version. This is meant as a help for the + writer of the "What's New" document. + * "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. - * "changes", which builds an overview over all versionadded/versionchanged/ - deprecated items in the current version. This is meant as a help for the - writer of the "What's New" document. - * "coverage", which builds a coverage overview for standard library modules and C API. + * "doctest", which runs doctests in the documentation. + * "pydoc-topics", which builds a Python module containing a dictionary with plain text documentation for the labels defined in `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and keyword help. -A "make update" updates the Subversion checkouts in `tools/`. + * "dist", which builds all styles and prepares them for packaging. On Unix, + the packaging is done for you. + + * "suspicious", which checks for suspicious markup. + + * "check", which checks for frequent markup errors. + + * "serve", which serves the build/html directory on port 8000. Without make @@ -99,7 +120,7 @@ You can optionally also install Pygments, either as a checkout via :: - svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments + svn co http://svn.python.org/projects/external/Pygments-1.5dev-20120930/pygments tools/pygments or from PyPI at http://pypi.python.org/pypi/Pygments. @@ -108,8 +129,8 @@ python tools/sphinx-build.py -b . build/ -where `` is one of html, text, latex, or htmlhelp (for explanations see -the make targets above). +where `` is one of html, text, latex, epub, or htmlhelp (for +explanations see the make targets above). Contributing diff --git a/Doc/make.bat b/Doc/make.bat --- a/Doc/make.bat +++ b/Doc/make.bat @@ -1,59 +1,356 @@ -@@echo off +@echo off +rem The following variables can be set in your environment to change the way +rem this script executes: +rem PYTHON2 +rem PYTHON3 +rem SVNROOT +rem HTMLHELP +rem SPHINXOPTS +rem PAPER +rem SOURCES +rem DISTVERSION +rem SPHINXVERSION +rem DOCUTILSVERSION +rem JINJAVERSION +rem PYGMENTSVERSION +rem +rem These can also be set from the command line, e.g. +rem make html "PYTHON2=py -2.7" +rem Note that there MUST be double quotes around the assignment! + + setlocal +pushd %~dp0 -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 +set this=%~n0 -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 -:help -set this=%~n0 -echo HELP -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. +rem Parse the command line arguments using horrific black magic of the +rem foulest kind. First argument becomes BUILDER, all others either become +rem part of SOURCES or set a variable of their own. + +set BUILDER=%1 + +:parse-arg-loop +shift +if [%1] EQU [] goto after-parse-loop + +echo %1 | findstr /C:"=" 1>nul + +if %ERRORLEVEL% EQU 1 ( + set SOURCES=%SOURCES% %1 +) else ( + set %1 +) +goto parse-arg-loop +:after-parse-loop + + + +rem Set defaults if there's nothing in the necessary variables. + +if "%PYTHON2%" EQU "" ( + if "%PYTHON%" EQU "" ( + set PYTHON2=py -2 + ) else ( + set PYTHON2=%PYTHON% + ) +) + +if "%PYTHON3%" EQU "" ( + if EXIST ..\PCbuild\amd64\python.exe ( + set PYTHON3=..\PCbuild\amd64\python.exe + ) else if EXIST ..\PCbuild\amd64\python_d.exe ( + set PYTHON3=..\PCbuild\amd64\python_d.exe + ) else if EXIST ..\PCbuild\python.exe ( + set PYTHON3=..\PCbuild\python.exe + ) else if EXIST ..\PCbuild\python_d.exe ( + set PYTHON3=..\PCbuild\python_d.exe + ) else ( + set PYTHON3=py -3 + ) +) + +if "%SNVROOT%" EQU "" set SVNROOT=http://svn.python.org/projects + +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 (`%PYTHON2% tools/sphinxext/patchlevel.py`) do set DISTVERSION=%%v + + +rem ########################################################################## +rem Make sure these match the versions in Makefile! + +if "%SPHINXVERSION%" EQU "" set SPHINXVERSION=Sphinx-1.0.7 + +if "%DOCUTILSVERSION%" EQU "" set DOCUTILSVERSION=docutils-0.6 + +if "%JINJAVERSION%" EQU "" set JINJAVERSION=Jinja-2.3.1 + +if "%PYGMENTSVERSION%" EQU "" set PYGMENTSVERSION=Pygments-1.5dev-20120930 + +rem ########################################################################## + +rem Go to the appropriate target. If %BUILDER% is not in this list, fall +rem through to a help message. + +for %%x in ( + clean, update, html, htmlhelp, htmlview, latex, text, epub, changes, + linkcheck, coverage, doctest, pydoc-topics, dist, suspicious, + check, serve +) do if "%BUILDER%" EQU "%%x" goto %%x + +echo Please use "%this% " where ^ 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 htmlview to make HTML files and open a webbrowser to the main page +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 +echo doctest to run doctests in the documentation +echo pydoc-topics to regenerate the pydoc topics file +echo dist to create a "dist" directory with archived docs for download +echo suspicious to check for suspicious markup in output text +echo check to run a check for frequent markup errors +echo serve to serve the documentation on the localhost (8000) 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.5dev-20120930/pygments tools/pygments + + +:clean +pushd . +rmdir /S /Q build +rmdir /S /Q tools\sphinx +rmdir /S /Q tools\docutils +rmdir /S /Q tools\jinja2 +rmdir /S /Q tools\pygments goto end + + :update -svn update tools/sphinx -svn update tools/docutils -svn update tools/jinja2 -svn update tools/pygments +pushd . +call :clean +call :checkout 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% --version -cmd /C %PYTHON% tools\sphinx-build.py -b%1 -dbuild\doctrees . build\%* -if "%1" EQU "htmlhelp" "%HTMLHELP%" build\htmlhelp\python%DISTVERSION:.=%.hhp + + +:html +pushd . +call :build +echo Build finished; the HTML pages are in build\html. goto end + + +:htmlhelp +pushd . +call :build +echo Build finished; the HTML pages are in build\htmlhelp. + +cmd /C "%HTMLHELP% build\htmlhelp\python%DISTVERSION:.=%.hhp" + +if EXIST "%~dp0build\htmlhelp\python%DISTVERSION:.=%.chm" ( + echo The compiled help file is at build\htmlhelp\python%DISTVERSION:.=%.chm. +) else ( + echo HTML Help Workshop could not be built. There should be an + echo error message above. +) +goto end + + + +:htmlview +set BUILDER=html +call :build +echo Build finished; opening web browser... + +rem Much easier to let Windows figure out how to open it than to try to use +rem the webbrowser module like Makefile does +cmd /C build\html\index.html +goto end + + + +:latex +pushd . +call :build +echo Build finished; the LaTeX files are in build\latex. +goto end + + + +:text +pushd . +call :build +echo Build finished; the text files are in build\text. +goto end + + + +:epub +pushd . +call :build +echo Build finished; the epub files are in build\epub. +goto end + + + +:changes +pushd . +call :build +echo The overview file is in build\changes. +goto end + + + +:linkcheck +pushd . +call :build +echo Link check complete; look for any errors in the above output +echo or in build\linkcheck\output.txt. +goto end + + + +:coverage +pushd . +call :build +echo Coverage finished; see c.txt and python.txt in build\coverage. +goto end + + + +:doctest +pushd . +call :build +echo Testing of doctests in the sources finished, look at the +echo results in build\doctest\output.txt. +goto end + + + +:pydoc-topics +pushd . +call :build +echo Building finished, now copy build\pydoc-topics\topics.py +echo to ..\Lib\pydoc_data\topics.py. +goto end + + + +:dist +pushd . +if exist dist rmdir /S /Q dist +mkdir dist + +set SOURCES= + +set BUILDER=html +call :build +echo Copying html... +xcopy /E /I /Q build\html dist\python-%DISTVERSION%-docs-html + +set BUILDER=text +call :build +echo Copying text... +xcopy /E /I /Q build\text dist\python-%DISTVERSION%-docs-text + +set BUILDER=latex +if exist build\latex rmdir /S /Q build\latex +set PAPER=a4 +call :build +echo Copying LaTeX... +xcopy /E /I /Q build\latex dist\python-%DISTVERSION%-docs-latex-a4 + +rmdir /S /Q build\latex +set PAPER=letter +call :build +echo Copying LaTeX... +xcopy /E /I /Q build\latex dist\python-%DISTVERSION%-docs-latex-letter + +set BUILDER=epub +call :build +echo Copying epub... +xcopy /E /I /Q build\epub dist\python-%DISTVERSION%-docs-epub + +echo Docs are ready for packaging in the dist directory. The LaTeX files will +echo need to be compiled as well. +goto end + + + +:suspicious +pushd . +call :build +echo Suspicious check complete; look for any errors in the above output +echo or in build\suspicious\suspicious.csv. If all issues are false +echo positives, append that file to tools\sphinxext\susp-ignored.csv. +goto end + + + +:check +pushd . +cmd /C %PYTHON2% tools\rstlint.py -i tools +goto end + + + +:serve +pushd . +cmd /C %PYTHON3% ..\Tools\scripts\serve.py build/html +goto end + + + +:checkout +pushd . +if not exist tools\sphinx ( +echo Checking out Sphinx... +svn co %SVNROOT%/external/%SPHINXVERSION%/sphinx tools/sphinx) + +if not exist tools\docutils ( +echo Checking out Docutils... +svn co %SVNROOT%/external/%DOCUTILSVERSION%/docutils tools/docutils) + +if not exist tools\jinja2 ( +echo Checking out Jinja... +svn co %SVNROOT%/external/%JINJAVERSION%/jinja2 tools/jinja2) + +if not exist tools\pygments ( +echo Checking out Pygments... +svn co %SVNROOT%/external/%PYGMENTSVERSION%/pygments tools/pygments) +goto end + + + +:build +pushd . +call :checkout + +if not exist build mkdir build +if not exist build\%BUILDER% mkdir build\%BUILDER% +if not exist build\doctrees mkdir build\doctrees + +set ALLSPHINXOPTS=-b %BUILDER% -d build/doctrees -D latex_paper_size=%PAPER% %SPHINXOPTS% . build/%BUILDER% %SOURCES% + +cmd /C %PYTHON2% --version +cmd /C %PYTHON2% tools\sphinx-build.py %ALLSPHINXOPTS% + +echo. + +goto end + + + :end +popd