8000 Document how to rebuild only one or a few docs files · Issue #1309 · python/devguide · GitHub
[go: up one dir, main page]
Skip to content

Document how to rebuild only one or a few docs files #1309

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.

Sign up for GitHub

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

Jump to bottom
Open
hugovk opened this issue Apr 18, 2024 · 5 comments
8000
Open

Document how to rebuild only one or a few docs files #1309

hugovk opened this issue Apr 18, 2024 · 5 comments
Labels
good first issue New contributors guide-new content Additions; New content or section needed help wanted

Comments

@hugovk
Copy link
Member
hugovk commented Apr 18, 2024

Let's document the method to build docs but only rebuild one or a few files like make -C Doc html SOURCES=<path>, it can be much quicker than rebuilding the whole set.

For example:

  • make -C Doc html SOURCES=whatsnew/3.13.rst
  • make -C Doc html SOURCES="whatsnew/3.13.rst whatsnew/3.12.rst" (double check this syntax)

And I think it might be Unix only?
@hugovk hugovk added help wanted good first issue New contributors guide-new content Additions; New content or section needed labels Apr 18, 2024
@AmboThom
Copy link

Hi @hugovk,

I'm willing to take this issue and it might take me about 2 weeks to work on this task. Before I start have a few questions:

  • Where would the method to build the docs go? Would it be on a new page or added to an existing page? If it's an existing page, maybe this page or here.
  • You mentioned a few files, do you know the maximum amount of docs that can be built this way?

It might take me about 2 weeks to work on this task.

@AA-Turner
Copy link
Member

And I think it might be Unix only?

More precisely, platforms that support make -- I believe it is possible to use on Windows via cygwin.

On Windows (or any platform), one can use sphinx-build -M Doc Doc/build [SOURCES], though you need to run blurb merge yourself.

It might take me about 2 weeks to work on this task.

There's no rush in terms of a PR, but I wouldn't expect this to take a fortnight to write up -- to set expectations, this would only be a paragraph or two of extra text

Where would the method to build the docs go?

I'd suggest in the "Building the documentation" section

the maximum amount of docs that can be built this way?

No limit is imposed. But we should suggest only using this in sensible cases, such as those that Hugo outlined.

A

@MichaByte
Copy link

Heya, this seems stale. Does anyone mind if I take a crack at it?

@hugovk
Copy link
Member Author
hugovk commented May 19, 2025

@MichaByte Please do!

MichaByte added a commit to MichaByte/devguide that referenced this issue May 19, 2025
@MichaByte
pythongh-1309: Document how to selectively build RST pages
6670c74
@MichaByte
Copy link

I just made #1562!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
good first issue New contributors guide-new content Additions; New content or section needed help wanted
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@hugovk @AA-Turner @MichaByte @AmboThom
0