Skip to content

DOC: move doc build options into tables and tabs #31025

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

Merged
timhoffm merged 1 commit into from
Jan 24, 2026
Merged

DOC: move doc build options into tables and tabs #31025

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
83 changes: 55 additions & 28 deletions doc/devel/document.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,49 +70,76 @@ used. To build the documentation in html format, cd into :file:`doc/` and run:

Build options
-------------
Other useful invocations include:

.. list-table::
:widths: 30 30 40
:header-rows: 1
:stub-columns: 1

* - invocation
- description
- notes
* - ``make html-noplot``
- skip generation of the gallery images
-
* - ``make html-skip-subdirs``
- skip specific subdirectories
- If a gallery directory is skipped, the gallery images are not generated. The first
time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited to add
or remove subdirectories
* - ``make clean``
- Delete built files.
- May help if you get errors about missing paths or broken links.
* - ``make latexpdf``
- Build pdf docs
-

Other useful invocations include
The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build
the complete docs but exit with exit status 1 if there are warnings. To unset it, set
the variable to a blank space. On Windows, set the options as environment variables.

.. code-block:: sh
.. tab-set::
:sync-group: category

# Build the html documentation, but skip generation of the gallery images to
# save time.
make html-noplot
.. tab-item:: Linux & macOS
:sync: linux

# Build the html documentation, but skip specific subdirectories. If a gallery
# directory is skipped, the gallery images are not generated. The first
# time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited
# to add or remove subdirectories
make html-skip-subdirs
.. code-block:: sh

# Delete built files. May help if you get errors about missing paths or
# broken links.
make clean
make SPHINXOPTS= html

# Build pdf docs.
make latexpdf
.. tab-ITEM:: Windows
:sync: windows

The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build
the complete docs but exit with exit status 1 if there are warnings. To unset
it, use

.. code-block:: sh
.. code-block:: bat

make SPHINXOPTS= html
set SPHINXOPTS= & make html

You can use the ``O`` variable to set additional options:

* ``make O=-j4 html`` runs a parallel build with 4 processes.
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
* ``O=-j4`` runs a parallel build with 4 processes.
* ``O=-Dplot_formats=png:100`` saves figures in low resolution.

Multiple options can be combined, e.g:

.. tab-set::
:sync-group: category

.. tab-item:: Linux & macOS
:sync: linux

.. code-block:: sh

make SPHINXOPTS= O='-j4 -Dplot_formats=png:100' html

Multiple options can be combined, e.g. ``make O='-j4 -Dplot_formats=png:100'
html``.
.. tab-ITEM:: Windows
:sync: windows

On Windows, set the options as environment variables, e.g.:
.. code-block:: bat

.. code-block:: bat
set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html

set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html

Show locally built docs
-----------------------
Expand Down
Loading