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

Skip to content

Commit c8c0129

Browse files
fredrik-1fredrik-1
committed
changes in building the documentation
1 parent f881e9b commit c8c0129

File tree

2 files changed

+97
-12
lines changed

2 files changed

+97
-12
lines changed

‎doc/devel/documenting_mpl.rst

Lines changed: 88 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.2.0
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,89 @@ 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+
113+
The documentation is build using the ``make.bat`` file. The options are set using
114+
environment variables and variables can be set either in the
115+
``make.bat`` file or set on the command line befor running ``make.bat``.
116+
117+
Environment variables are set with
118+
119+
.. code-block:: sh
120+
121+
#in cmd
122+
set SPHINXOPTS=-W
123+
set O=-Dplot_gallery=0
94124
95-
Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
96-
html``.
125+
#in powershell
126+
Set-Item env:SPHINXOPTS "-W"
127+
Set-Item env:O "-Dplot_gallery=0"
128+
129+
The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
130+
errors. To unset it, set the ``SPHINXOPTS`` variable to any argument except
131+
nothing. A space can used to overide the default.
132+
133+
.. code-block:: sh
134+
135+
#in cmd
136+
#use the default -W option
137+
make html
138+
set SPHINXOPTS=& make html
139+
140+
#to not use the default
141+
set SPHINXOPTS= & make html
142+
143+
You can use the ``O`` variable to set additional options, for example (see
144+
linux, macOS above for more options)
97145

98-
On Windows, options needs to be set as environment variables, e.g. ``set O=-W
99-
-j4 & make html``.
146+
.. code-block:: sh
147+
148+
set O=-j4 -Dplot_gallery=0
149+
150+
The total command is then run with
151+
152+
.. code-block:: sh
153+
154+
#in cmd
155+
set O=-Dplot_gallery=0
156+
make html
157+
158+
#or on one line
159+
set O=-Dplot_gallery=0 & make html
160+
161+
#in powershell
162+
Set-Item env:O "-Dplot_gallery=0"
163+
.\make html
164+
165+
#or on one line
166+
Set-Item env:O "-Dplot_gallery=0"; .\make html
167+
168+
Both ``SPHINXOPTS`` and ``O`` are unset at the end of the ``make.bat`` file
169+
if cmd is used but not if powershell is used. So a variable must be unset
170+
manually with
171+
172+
.. code-block:: sh
100173
174+
Set-Item evn:O
175+
176+
in powershell before running ``make.bat`` again if the default behavior is
177+
wanted.
178+
101179
.. _writing-rest-pages:
102180

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