Skip to content

Infra: Use consistent 'make html' and 'make dirhtml' #2968

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 19, 2023

Conversation

hugovk
Copy link
Member

@hugovk hugovk commented Jan 17, 2023

I keep forgetting what make render and make pages actually do, and to be sure need to check how the Makefile calls build.py and how that calls sphinx-build.

Let's add make html and make dirhtml aliases.

These are the actual Sphinx builder names, and the same Makefile targets are used by other Sphinx/Python projects, including CPython docs and the devguide, so we can use muscle memory.

(They're also the default for new Sphinx projects.)

And then I don't think we need the old make render and make pages and can mark them as deprecated?

@hugovk hugovk added the infra Core infrastructure for building and rendering PEPs label Jan 17, 2023
@hugovk hugovk requested review from AA-Turner, CAM-Gerlach and a team as code owners January 17, 2023 17:23
@hugovk hugovk force-pushed the consistent-make-html-dirhtml branch from d8c9ee9 to 733e21d Compare January 17, 2023 17:24
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, makes sense (I'd get confused too).

Though to be honest I don't ever actually use the Makefile (or even build.py, since it basically just wraps a limited subset of Sphinx's interface)—I just run python -m sphinx . build instead, which does exactly the same thing but gives me the full power of Sphinx's native CLI, including writing out only one specific PEP, writing to separate build dirs, passing -b -X dev to get Python-level warnings, etc. And, of course, it lets me use my Conda env and test different Sphinx and tool versions vs. the hardcoded venv.

@Rosuav
Copy link
Contributor

Rosuav commented Jan 17, 2023

LGTM. I've only ever used the defaults but consistency is always a good thing.

@hugovk hugovk merged commit 55ef1f4 into python:main Jan 19, 2023
@hugovk hugovk deleted the consistent-make-html-dirhtml branch January 19, 2023 14:39
@hugovk hugovk mentioned this pull request Oct 28, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
infra Core infrastructure for building and rendering PEPs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants