Skip to content

Some changes in make.bat and the build documentation documentation #11121

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

Closed
wants to merge 1 commit into from
Closed

Some changes in make.bat and the build documentation documentation #11121

Show file tree
Hide file tree
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
98 changes: 88 additions & 10 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ requirements that are needed to build the documentation. They are listed in
* IPython
* numpydoc>=0.4
* Pillow
* sphinx-gallery>=0.1.13
* sphinx-gallery>=0.2.0
* graphviz

.. note::
Expand All @@ -72,13 +72,18 @@ Other useful invocations include

.. code-block:: sh

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

# Build pdf docs.
make latexpdf

Linux, macOS
~~~~~~~~~~~~
The documentation is built using the ``Makefile`` file and parameters
can be set either in the ``Makefile`` or on the command line.

The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
errors. To unset it, use

Expand All @@ -88,16 +93,89 @@ errors. To unset it, use

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.
* ``make O=-Dplot_gallery=0 html`` skips the gallery build.
.. code-block:: sh

#runs a parallel build with 4 processes.
Copy link
Member

Choose a reason for hiding this comment

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

I'd go for # run a parallel build with 4 processes, i.e. use an imperative style rather than a statement, similar to how we write docstrings. The same holds for the following two comments.

Please also add a space between # and text (multiple places throughout the PR).

make O=-j4 html

#saves figures in low resolution.
make O=-Dplot_formats=png:100 html

#builds the gallery without executing the scripts
make O=-Dplot_gallery=0 html

#Multiple options can be combined using e.g.
make O='-j4 -Dplot_gallery=0' html

Windows
~~~~~~~

The documentation is build using the ``make.bat`` file. The options are set using
Copy link
Member

Choose a reason for hiding this comment

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

using the make.bat file

environment variables and variables can be set either in the
Copy link
Member

Choose a reason for hiding this comment

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

a bit less repetitive:

The options are controlled using environment variables. They can be set either in make.bat or on the command line before running make.bat.

``make.bat`` file or set on the command line befor running ``make.bat``.

Environment variables are set with

.. code-block:: sh

#in cmd
set SPHINXOPTS=-W
Copy link
Member

Choose a reason for hiding this comment

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

Can we use an example that is not the default value? IMHO that would make more sense.

set O=-Dplot_gallery=0

Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
html``.
#in powershell
Copy link
Member

Choose a reason for hiding this comment

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

PowerShell is a proper name, so we should capitalize it appropriately (multiple occurences throughout the PR).

Set-Item env:SPHINXOPTS "-W"
Set-Item env:O "-Dplot_gallery=0"

The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
errors. To unset it, set the ``SPHINXOPTS`` variable to any argument except
nothing. A space can used to overide the default.

.. code-block:: sh

#in cmd
#use the default -W option
make html
set SPHINXOPTS=& make html
Copy link
Member

Choose a reason for hiding this comment

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

Can be left out. Or if you insist, put a # or line above.


#to not use the default
set SPHINXOPTS= & make html

You can use the ``O`` variable to set additional options, for example (see
linux, macOS above for more options)

On Windows, options needs to be set as environment variables, e.g. ``set O=-W
-j4 & make html``.
.. code-block:: sh

set O=-j4 -Dplot_gallery=0

The total command is then run with

.. code-block:: sh

#in cmd
set O=-Dplot_gallery=0
make html

#or on one line
set O=-Dplot_gallery=0 & make html

#in powershell
Set-Item env:O "-Dplot_gallery=0"
.\make html

#or on one line
Set-Item env:O "-Dplot_gallery=0"; .\make html

Both ``SPHINXOPTS`` and ``O`` are unset at the end of the ``make.bat`` file
if cmd is used but not if powershell is used. So a variable must be unset
manually with

.. code-block:: sh

Set-Item evn:O

in powershell before running ``make.bat`` again if the default behavior is
wanted.

.. _writing-rest-pages:

Writing ReST pages
Expand Down
11 changes: 9 additions & 2 deletions doc/make.bat
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@ if "%SPHINXBUILD%" == "" (
set SOURCEDIR=.
set BUILDDIR=build
set SPHINXPROJ=matplotlib
set SPHINXOPTS=-W
set O=

if "%SPHINXOPTS%" == "" (
Copy link
Member

Choose a reason for hiding this comment

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

Go for if not defined SPHINXOPTS https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/if.

That also makes it possible to use set SPHINXOPTS=& make html for setting an empty variable, i.e. we do not need the "set to anything but nothing" workaround.

set SPHINXOPTS=-W
)

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
Expand All @@ -28,11 +30,16 @@ if errorlevel 9009 (

if "%1" == "" goto help

echo %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help

%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
set SPHINXBUILD=
set O=
set SPHINXOPTS=
popd