changes in building the documentation

fredrik-1 · fredrik-1 · commit 9f282128095d · 2018-04-25T10:07:40.000+02:00
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -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
 
@@ -88,16 +93,85 @@ 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.
+    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
+~~~~~~~
+.. note::
+
+    It is currently not possible to build the gallery on windows due to a 
+    problem in sphinx-gallery that should be fixed in version 0.1.14. A 
+    workaround is to not build the gallery by commenting out 
+    ``sphinx_gallery.gen_gallery`` in ``extensions`` in the ``conf.py`` file 
+    or to delete the code in or delete the  
+    ``examples\userdemo\pgf_preamble_sgskip.py`` file.
+     
+The documentation is build using the ``make.bat`` file. The options are set using 
+environment variables and varibales can be set either in the 
+``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
+    set O=-Dplot_gallery=0  
+
+    #in powershell
+    Set-Item env:SPHINXOPTS "-W"
+    Set-Item env:O "-Dplot_gallery=0" 
 
-Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
-html``.
+Set ``SPHINXOPTS`` to ``-W`` to turn warnings into errors.
+   
+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
+         
+There is no difference between the variables ``SPHINXOPTS`` and ``O`` and both 
+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
diff --git a/doc/make.bat b/doc/make.bat
@@ -10,8 +10,6 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=.
 set BUILDDIR=build
 set SPHINXPROJ=matplotlib
-set SPHINXOPTS=-W
-set O=
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -28,11 +26,15 @@ 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 O=
+set SPHINXOPTS=
 popd
