Skip to content

#116 (bpo-29563): update doc building section. #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 23, 2017
Merged

#116 (bpo-29563): update doc building section. #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions docquality.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <pullrequest>` 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 <pullrequest>` 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
Expand All @@ -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.
Expand Down Expand Up @@ -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 <pullrequest>`, so you should make
sure that it runs without errors.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't actually seem to be the case for the devguide repo, so either the sentence should be removed or the check should be added.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 on adding make check to the devguide repo.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where should we report this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd create a new issue at https://github.com/python/devguide/issues

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in #132


Changes to the devguide are normally published within a day, on a schedule
that may be different from the main documentation.
Expand Down
56 changes: 12 additions & 44 deletions documenting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<checkout>`::
**On Unix**, run the following from the root of your :ref:`repository clone
<checkout>` 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 <pullrequest>`, 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
Expand Down