Repository navigation
running 'make html' from the Doc tree emits an unwelcoming error message #81019
Description
| BPO | 36838 |
|---|---|
| Nosy | @gpshead |
| PRs |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/gpshead'
closed_at = <Date 2019-05-07.21:04:44.013>
created_at = <Date 2019-05-07.19:37:17.697>
labels = ['build', '3.8']
title = "running 'make html' from the Doc tree emits an unwelcoming error message"
updated_at = <Date 2019-05-07.21:04:44.012>
user = 'https://github.com/gpshead'bugs.python.org fields:
activity = <Date 2019-05-07.21:04:44.012>
actor = 'gregory.p.smith'
assignee = 'gregory.p.smith'
closed = True
closed_date = <Date 2019-05-07.21:04:44.013>
closer = 'gregory.p.smith'
components = ['Build']
creation = <Date 2019-05-07.19:37:17.697>
creator = 'gregory.p.smith'
dependencies = []
files = []
hgrepos = []
issue_num = 36838
keywords = ['patch']
message_count = 3.0
messages = ['341806', '341814', '341824']
nosy_count = 1.0
nosy_names = ['gregory.p.smith']
pr_nums = ['13173']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'compile error'
url = 'https://bugs.python.org/issue36838'
versions = ['Python 3.8']
Activity
gpshead commentedon May 7, 2019
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).
Doc builders need to run
make -C Doc venvfirst. 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.gpshead commentedon May 7, 2019
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).
gpshead commentedon May 7, 2019
New changeset 3918ad6 by Gregory P. Smith in branch 'master':
bpo-36838: Suggest 'make venv' when missing Doc/ tools. (GH-13173)
3918ad6