This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: running 'make html' from the Doc tree emits an unwelcoming error message
Type: compile error Stage: resolved
Components: Build Versions: Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: gregory.p.smith Nosy List: gregory.p.smith
Priority: normal Keywords: patch

Created on 2019-05-07 19:37 by gregory.p.smith, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 13173 merged gregory.p.smith, 2019-05-07 20:16
Messages (3)
msg341806 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2019-05-07 19:37
Running make in the Doc directory does not install all necessary tooling on its own.  This is a hurdle to getting beginners up to speed on making documentation changes (often their very first changes in the CPython project).

```
:~/oss/cpython/throwaway:master$ make -C Doc html
make: Entering directory '/.../oss/cpython/throwaway/Doc'
mkdir -p build
Building NEWS from Misc/NEWS.d with blurb
/bin/sh: line 5: blurb: command not found
Makefile:44: recipe for target 'build' failed
make: *** [build] Error 127
make: Leaving directory '/.../oss/cpython/throwaway/Doc'
```

Doc builders need to run `make -C Doc venv` first.  Just updating the logic to print that as an error message when the venv or any of the necessary tools within it are missing would be more welcoming.
msg341814 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2019-05-07 20:28
I noted this at the mentored sprints this year when I suggested my mentee "cd Doc ; make html" to show them how to build the docs, check that they build and see what they look like.

Once upon a time we used to auto-fetch and install sphinx (long ago?), this appears to have changed to make venv.  This PR at least tells people what to do.  Having the build file auto create the venv is... not quite desired.  The way the Makefile is setup, it'll all still work if people have a late enough blurb and sphinx-build on their PATH.  if we auto install the venv, those installed tools will override _both_ of those so if someone _wanted_ the version on their PATH for some reason it would override that (... i really don't recommend it but i'm not gonna break this for blurb or sphinx developers who may like this).
msg341824 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2019-05-07 21:03
New changeset 3918ad6b45da31e05265de5a455102276717c659 by Gregory P. Smith in branch 'master':
bpo-36838: Suggest 'make venv' when missing Doc/ tools. (GH-13173)
https://github.com/python/cpython/commit/3918ad6b45da31e05265de5a455102276717c659
History
Date User Action Args
2022-04-11 14:59:14adminsetgithub: 81019
2019-05-07 21:04:44gregory.p.smithsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-05-07 21:03:53gregory.p.smithsetmessages: + msg341824
2019-05-07 20:28:59gregory.p.smithsetmessages: + msg341814
2019-05-07 20:16:08gregory.p.smithsetkeywords: + patch
stage: patch review
pull_requests: + pull_request13089
2019-05-07 20:09:43gregory.p.smithsetassignee: gregory.p.smith
2019-05-07 19:37:17gregory.p.smithcreate