Skip to content

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.

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

gh-1309: Document how to selectively build RST pages #1562

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions documentation/start-documenting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,25 @@ To build the docs as HTML, run:
start a local server, and automatically reload the page in your
Copy link
Contributor

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?

browser when you make changes to reST files (Unix only).

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:
Comment on lines +156 to +158
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
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.


.. tab:: Unix/macOS

.. code-block:: shell

make html SOURCES="tutorial/classes.rst tutorial/inputoutput.rst"

.. tab:: Windows

See :ref:`using-sphinx-build`. When invoking ``sphinx-build``, pass the
desired pages as the final parameter, like so:
Comment on lines +168 to +169
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
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.


.. code-block:: dosbatch

python -m sphinx -b html . build/html tutorial/classes.rst tutorial/inputoutput.rst

To check the docs for common errors with `Sphinx Lint`_
(which is run on all :ref:`pull requests <pullrequest>`), use:

Expand Down
Loading