Message287808
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. |
|
Date |
User |
Action |
Args |
2017-02-15 02:46:18 | JDLH | set | recipients:
+ JDLH, docs@python |
2017-02-15 02:46:18 | JDLH | set | messageid: <1487126778.41.0.112837375413.issue29563@psf.upfronthosting.co.za> |
2017-02-15 02:46:18 | JDLH | link | issue29563 messages |
2017-02-15 02:46:17 | JDLH | create | |
|