From 9928e1d3b9beb38cf64c004803cd7b38db2f9a49 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 23 Feb 2017 03:44:41 +0200 Subject: [PATCH] #116 (bpo-29563): update doc building section. --- docquality.rst | 10 +++++---- documenting.rst | 56 +++++++++++-------------------------------------- 2 files changed, 18 insertions(+), 48 deletions(-) diff --git a/docquality.rst b/docquality.rst index 5ffb61ef8..4e8ef26db 100644 --- a/docquality.rst +++ b/docquality.rst @@ -36,8 +36,8 @@ If you look at `documentation issues`_ on the `issue tracker`_, you will find various documentation problems that need work. Issues vary from typos, to unclear documentation, to something completely lacking documentation. -If you decide to tackle a documentation issue, you can simply submit a -:doc:`pull request ` for the issue. If you are worried that someone +If you decide to tackle a documentation issue, you can simply submit a +:doc:`pull request ` for the issue. If you are worried that someone else might be working simultaneously on the issue, simply leave a comment on the issue saying you are going to try and create a pull request and roughly how long you think you will take to do it (this allows others to take on the issue if you happen @@ -57,7 +57,7 @@ uncover problems (e.g., documentation that needs to be updated for Python 3 from Python 2). If you decide to proofread, then read a section of the documentation from start -to finish, filing issues in the issue tracker for each problem you find. Simple +to finish, filing issues in the issue tracker for each problem you find. Simple typos don't require an issue of their own, instead submit a pull request directly. Don't file a single issue for an entire section containing multiple problems as that makes it harder to break the work up for multiple people to help with. @@ -88,7 +88,9 @@ installed. The devguide HTML can be built by running:: $ make html in the checkout directory, which will write the files to the ``_build/html`` -directory. +directory. Note that ``make check`` is automatically run when +you submit a :doc:`pull request `, so you should make +sure that it runs without errors. Changes to the devguide are normally published within a day, on a schedule that may be different from the main documentation. diff --git a/documenting.rst b/documenting.rst index 4e96fb72f..7a48fe6fd 100644 --- a/documenting.rst +++ b/documenting.rst @@ -1460,62 +1460,30 @@ a browser at the file :file:`Doc/build/html/index.html`. You are expected to have installed the latest stable version of Sphinx_ on your system or in a virtualenv_, so that the Makefile can find the -``sphinx-build`` command. +``sphinx-build`` command. You can also specify the location of +``sphinx-build`` with the ``SPHINXBUILD`` :command:`make` variable. Using make / make.bat --------------------- -On Unix, run the following from the root of your :ref:`repository clone -`:: +**On Unix**, run the following from the root of your :ref:`repository clone +` to build the output as HTML:: cd Doc make html -or alternatively ``make -C Doc html``. This builds the output as HTML. You can -specify the location of the ``sphinx-build`` command with the ``SPHINXBUILD`` -make variable. +or alternatively ``make -C Doc html``. -For Windows users there is a :file:`make.bat` batchfile that tries to work like -``make`` does. +You can also use ``make help`` to see a list of targets supported by +:command:`make`. Note that ``make check`` is automatically run when +you submit a :doc:`pull request `, so you should make +sure that it runs without errors. -Available :command:`make` targets are: +**On Windows**, there is a :file:`make.bat` batchfile that tries to +emulate :command:`make` as closely as possible. - * "html", which builds standalone HTML files for offline viewing. - - * "htmlview", which builds the standalone HTML files and then opens a web - browser to display them. - - * "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. - - * "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. - - * "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. - - * "pydoc-topics", which builds a Python module containing a dictionary with - plain text documentation for the labels defined in - :file:`Doc/tools/pyspecific.py` -- pydoc needs these to show topic - and keyword help. - - * "suspicious", which checks the parsed markup for text that looks like - malformed and thus unconverted reST. +See also :file:`Doc/README.rst` for more information. Without make