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

Skip to content

Commit 10a96be

Browse files
fredrik-1fredrik-1
committed
changes in building the documentation
1 parent c93957b commit 10a96be

File tree

2 files changed

+102
-11
lines changed

2 files changed

+102
-11
lines changed

‎doc/devel/documenting_mpl.rst‎

Lines changed: 93 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -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,95 @@ 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 currently not possible to build the gallery on windows due to a
115+
problem in sphinx-gallery that should be fixed in version 0.1.14. A
116+
workaround is to not build the gallery by commenting out
117+
``sphinx_gallery.gen_gallery`` in ``extensions`` in the ``conf.py`` file.
118+
119+
The documentation is build using the ``make.bat`` file. The options are set using
120+
environment variables and varibales can be set either in the
121+
``make.bat`` file or set on the command line befor running ``make.bat``.
122+
123+
Environment variables are set with
124+
125+
.. code-block:: sh
126+
127+
#in cmd
128+
set SPHINXOPTS=-W
129+
set O=-Dplot_gallery=0
130+
131+
#in powershell
132+
Set-Item env:SPHINXOPTS "-W"
133+
Set-Item env:O "-Dplot_gallery=0"
134+
135+
The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
136+
errors. To unset it, set the ``SPHINXOPTS`` variable to any argument except
137+
nothing. A space can used to overide the default.
138+
139+
.. code-block:: sh
140+
141+
#in cmd
142+
#use the default -W option
143+
make html
144+
set SPHINXOPTS=& make html
145+
146+
#to not use the default
147+
set SPHINXOPTS= & make html
148+
149+
You can use the ``O`` variable to set additional options, for example (see
150+
linux, macOS above for more options)
151+
152+
.. code-block:: sh
94153
95-
Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
96-
html``.
154+
set O=-j4 -Dplot_gallery=0
155+
156+
The total command is then run with
97157

98-
On Windows, options needs to be set as environment variables, e.g. ``set O=-W
99-
-j4 & make html``.
158+
.. code-block:: sh
159+
160+
#in cmd
161+
set O=-Dplot_gallery=0
162+
make html
163+
164+
#or on one line
165+
set O=-Dplot_gallery=0 & make html
166+
167+
#in powershell
168+
Set-Item env:O "-Dplot_gallery=0"
169+
.\make html
170+
171+
#or on one line
172+
Set-Item env:O "-Dplot_gallery=0"; .\make html
173+
174+
Both ``SPHINXOPTS`` and ``O`` are unset at the end of the ``make.bat`` file
175+
if cmd is used but not if
176+
powershell is used. So a variable must be unset manually with
177+
178+
.. code-block:: sh
100179
180+
Set-Item evn:O
181+
182+
in powershell before running ``make.bat`` again if the default behavior is
183+
wanted.
184+
101185
.. _writing-rest-pages:
102186

103187
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)