Author JDLH
Recipients JDLH, docs@python
Date 2017-02-15.02:46:17
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1487126778.41.0.112837375413.issue29563@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2017-02-15 02:46:18JDLHsetrecipients: + JDLH, docs@python
2017-02-15 02:46:18JDLHsetmessageid: <1487126778.41.0.112837375413.issue29563@psf.upfronthosting.co.za>
2017-02-15 02:46:18JDLHlinkissue29563 messages
2017-02-15 02:46:17JDLHcreate