[issue29563] Update Devguide about building documentation.

[Brett Cannon]

Brett Cannon added the comment:

Thanks for moving the issue, Jim!

--
resolution:  -> out of date
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29563] Update Devguide about building documentation.

[Jim DeLaHunt]

Jim DeLaHunt added the comment:

Per request from Brett Cannon, I've moved this issue to 
https://github.com/python/devguide/issues/116 . Please continue the discussion 
there.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29563] Update Devguide about building documentation.

[Brett Cannon]

Brett Cannon added the comment:

Would you mind moving this issue over to 
https://github.com/python/devguide/issues where we track devguide issues, Jim?

--
nosy: +brett.cannon

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29563] Update Devguide about building documentation.

[Zachary Ware]

Zachary Ware added the comment:

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.

--
nosy: +zach.ware

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29563] Update Devguide about building documentation.

[Jim DeLaHunt]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com