Author JDLH
Recipients JDLH, docs@python
Date 2017-02-15.02:46:17
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <>
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 ``. 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 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.
Date User Action Args
2017-02-15 02:46:18JDLHsetrecipients: + JDLH, docs@python
2017-02-15 02:46:18JDLHsetmessageid: <>
2017-02-15 02:46:18JDLHlinkissue29563 messages
2017-02-15 02:46:17JDLHcreate