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@python components: Documentation messages: 287808 nosy: JDLH, docs@python priority: normal severity: normal status: open title: Update Devguide about building documentation. type: enhancement versions: Python 3.7 _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue29563> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
