[docs] [issue29563] Update Devguide about building documentation.

[Jim DeLaHunt]

New submission from Jim DeLaHunt:

The Devguide section 7.5.1 "Building the documentation" / "Using make / make.bat" is out of date.  The document lists 10 documentation targets for `make`. The Doc/Makefile lists 17. 

One important omission is `make check`, which looks for errors in reStructuredText syntax, using `rstlint.py`. It's important for contributors to know about and to run `make check`, because with the move to GitHub, the project is running make check after pulling in new code.  If contributors haven't cleaned up their submissions, the build fails.

I suggest that the following improvements be made:

1. rewrite the bullet list "Available make targets are:" in 7.5.1 https://cpython-devguide.readthedocs.io/documenting.html#using-make-make-bat to match the list of targets in Doc/Makefile:21-38.

2. add a comment that `make help` will give the most up-to-date list of targets from the makefile, which might be better than the list in the Devguide.

3. add `make help` to both Doc/Makefile:21-38 and Devguide 7.5.1.

4. add to Devguide 6.3. "Helping with the Developer’s Guide" an instruction to run `make check` before submitting a pull request to the Devguide.

----------
assignee: docs at python
components: Documentation
messages: 287808
nosy: JDLH, docs at python
priority: normal
severity: normal
status: open
title: Update Devguide about building documentation.
type: enhancement
versions: Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue29563>
_______________________________________