Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork851
gh-1309: Document how to selectively build RST pages#1562
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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Uh oh!
There was an error while loading.Please reload this page.
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
IMO this does not need a whole section, I've never built specific pages, by the time I've written the commandmake html would have finished anyway. I don't see much need for this here, especially such a large section.
A better place would be above in the.. tip:: explaining you can passSOURCES="" with desired paths.
| It is also possible to build only certain pages of the documentation in order | ||
| to save time during the build process. Following is an example for building two | ||
| pages: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| It is also possible to build only certain pages of the documentation in order | |
| to save time during the build process. Following is an example for building two | |
| pages: | |
| To build only certain pages of the docs as HTML, run: |
It can be simpler, like the previous introduction.
| See :ref:`using-sphinx-build`. When invoking ``sphinx-build``, pass the | ||
| desired pages as the final parameter, like so: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| See:ref:`using-sphinx-build`.When invoking ``sphinx-build``, pass the | |
| desired pages as the final parameter, like so: | |
| When invoking ``sphinx-build``, pass the | |
| desired pages as the final parameter, like so: |
Do we need the reference here, if we really do IMO it is more natural to have it after i.e.
When ... parameter. See XXX.
| @@ -153,6 +153,25 @@ To build the docs as HTML, run: | |||
| start a local server, and automatically reload the page in your | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Why not just add it as a note here?
Stan, be aware that a lot of these changes are being discussed at the sprints in-person. |
I assumed so, yet I am not there :-(, so all I can do is comment. |
Right, but some changes have already been informally approved elsewhere, so it's not particularly helpful to say things like "IMO this does not need a whole section." I get that you're aspiring to be a triager or on the documentation team or whatever, but this isn't the way to go about it! Documentation reviews are the most helpful when they're about actually fixing typos or incorrect information, but wording and formality nitpicks (like you tend to suggest) are just noise that actuallyslow down documentation PRs. I think you would really benefit from having a core dev mentor that walked you through this. Have you asked around at all? |
Unfortunately I have no way of knowing this if it is not listed in the description.
It seems like quite an important thing in adocumentation pr.
You must have missed quite a few of my reviews then.
Yes, several months ago. |
Uh oh!
There was an error while loading.Please reload this page.
This PR adds a small section to
documentation/start-documentingthat informs the reader of how to build only certain documentation pages. I tested my instructions on Linux and Windows. Please let me know if any changes are needed!Thanks,
Micha
📚 Documentation preview 📚:https://cpython-devguide--1562.org.readthedocs.build/