Document how to rebuild only one or a few docs files

[hugovk]

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?

[AmboThom]

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]

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]

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

[hugovk]

@MichaByte Please do!

[MichaByte]

I just made #1562!