classification
Title: Update Devguide about building documentation.
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: JDLH, brett.cannon, docs@python, zach.ware
Priority: normal Keywords:

Created on 2017-02-15 02:46 by JDLH, last changed 2017-02-15 23:49 by brett.cannon. This issue is now closed.

Messages (5)
msg287808 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-15 02:46
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.
msg287814 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2017-02-15 03:58
I'd suggest replacing as much as possible in the devguide with a link to Doc/README.rst (or Doc/README.txt, if that's what it still is).  Other improvements should be made in the README.
msg287873 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-02-15 17:45
Would you mind moving this issue over to https://github.com/python/devguide/issues where we track devguide issues, Jim?
msg287889 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-15 21:54
Per request from Brett Cannon, I've moved this issue to https://github.com/python/devguide/issues/116 . Please continue the discussion there.
msg287903 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-02-15 23:49
Thanks for moving the issue, Jim!
History
Date User Action Args
2017-02-15 23:49:24brett.cannonsetstatus: open -> closed
resolution: out of date
messages: + msg287903

stage: resolved
2017-02-15 21:54:17JDLHsetmessages: + msg287889
2017-02-15 17:45:19brett.cannonsetnosy: + brett.cannon
messages: + msg287873
2017-02-15 03:58:25zach.waresetnosy: + zach.ware
messages: + msg287814
2017-02-15 02:46:18JDLHcreate