Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 7fa5ddb

Browse files
fredrik-1fredrik-1
committed
changes in building the documentation
1 parent 6665bc7 commit 7fa5ddb

File tree

2 files changed

+101
-12
lines changed

2 files changed

+101
-12
lines changed

‎doc/devel/documenting_mpl.rst

Lines changed: 92 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ requirements that are needed to build the documentation. They are listed in
4747
* IPython
4848
* numpydoc>=0.4
4949
* Pillow
50-
* sphinx-gallery>=0.1.13
50+
* sphinx-gallery>=0.1.13 (>=0.2.0 on windows)
5151
* graphviz
5252

5353
.. note::
@@ -72,13 +72,18 @@ Other useful invocations include
7272

7373
.. code-block:: sh
7474
75-
# Delete built files. May help if you get errors about missing paths or
76-
# broken links.
75+
# Delete built files. May help if you get errors about
76+
# missing paths or broken links.
7777
make clean
7878
7979
# Build pdf docs.
8080
make latexpdf
8181
82+
Linux, macOS
83+
~~~~~~~~~~~~
84+
The documentation is built using the ``Makefile`` file and parameters
85+
can be set either in the ``Makefile`` or on the command line.
86+
8287
The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
8388
errors. To unset it, use
8489

@@ -88,16 +93,93 @@ errors. To unset it, use
8893
8994
You can use the ``O`` variable to set additional options:
9095

91-
* ``make O=-j4 html`` runs a parallel build with 4 processes.
92-
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
93-
* ``make O=-Dplot_gallery=0 html`` skips the gallery build.
96+
.. code-block:: sh
97+
98+
#runs a parallel build with 4 processes.
99+
make O=-j4 html
100+
101+
#saves figures in low resolution.
102+
make O=-Dplot_formats=png:100 html
103+
104+
#builds the gallery without executing the scripts
105+
make O=-Dplot_gallery=0 html
106+
107+
#Multiple options can be combined using e.g.
108+
make O='-j4 -Dplot_gallery=0' html
109+
110+
Windows
111+
~~~~~~~
112+
.. note::
113+
114+
It is necessary to use sphinx-gallery >= 0.2.0 for building
115+
the documentation on windows.
116+
117+
The documentation is build using the ``make.bat`` file. The options are set using
118+
environment variables and varibales can be set either in the
119+
``make.bat`` file or set on the command line befor running ``make.bat``.
120+
121+
Environment variables are set with
122+
123+
.. code-block:: sh
94124
95-
Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
96-
html``.
125+
#in cmd
126+
set SPHINXOPTS=-W
127+
set O=-Dplot_gallery=0
97128
98-
On Windows, options needs to be set as environment variables, e.g. ``set O=-W
99-
-j4 & make html``.
129+
#in powershell
130+
Set-Item env:SPHINXOPTS "-W"
131+
Set-Item env:O "-Dplot_gallery=0"
132+
133+
The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
134+
errors. To unset it, set the ``SPHINXOPTS`` variable to any argument except
135+
nothing. A space can used to overide the default.
136+
137+
.. code-block:: sh
138+
139+
#in cmd
140+
#use the default -W option
141+
make html
142+
set SPHINXOPTS=& make html
143+
144+
#to not use the default
145+
set SPHINXOPTS= & make html
146+
147+
You can use the ``O`` variable to set additional options, for example (see
148+
linux, macOS above for more options)
149+
150+
.. code-block:: sh
151+
152+
set O=-j4 -Dplot_gallery=0
153+
154+
The total command is then run with
155+
156+
.. code-block:: sh
157+
158+
#in cmd
159+
set O=-Dplot_gallery=0
160+
make html
161+
162+
#or on one line
163+
set O=-Dplot_gallery=0 & make html
164+
165+
#in powershell
166+
Set-Item env:O "-Dplot_gallery=0"
167+
.\make html
168+
169+
#or on one line
170+
Set-Item env:O "-Dplot_gallery=0"; .\make html
171+
172+
Both ``SPHINXOPTS`` and ``O`` are unset at the end of the ``make.bat`` file
173+
if cmd is used but not if powershell is used. So a variable must be unset
174+
manually with
175+
176+
.. code-block:: sh
100177
178+
Set-Item evn:O
179+
180+
in powershell before running ``make.bat`` again if the default behavior is
181+
wanted.
182+
101183
.. _writing-rest-pages:
102184

103185
Writing ReST pages

‎doc/make.bat

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,11 @@ if "%SPHINXBUILD%" == "" (
1010
set SOURCEDIR=.
1111
set BUILDDIR=build
1212
set SPHINXPROJ=matplotlib
13-
set SPHINXOPTS=-W
14-
set O=
1513

14+
if "%SPHINXOPTS%" == "" (
15+
set SPHINXOPTS=-W
16+
)
17+
1618
%SPHINXBUILD% >NUL 2>NUL
1719
if errorlevel 9009 (
1820
echo.
@@ -28,11 +30,16 @@ if errorlevel 9009 (
2830

2931
if "%1" == "" goto help
3032

33+
echo %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
3134
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
3235
goto end
3336

3437
:help
38+
3539
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
3640

3741
:end
42+
set SPHINXBUILD=
43+
set O=
44+
set SPHINXOPTS=
3845
popd

0 commit comments

Comments
 (0)