Skip to content

Switch to makefile-based doc build. #9513

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

Merged
tacaswell merged 2 commits into from
Dec 3, 2017
Merged

Switch to makefile-based doc build. #9513

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8886a19
Switch to makefile-based doc build.
anntzer Oct 22, 2017
b4b1f64
Default to -W.
anntzer Dec 2, 2017
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
Prev Previous commit
Default to -W.
  • Loading branch information
@anntzer
anntzer committed Dec 2, 2017
commit b4b1f64275f26670056f23ef0c4e484ec66cadff
2 changes: 1 addition & 1 deletion .circleci/config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ mpl-run: &mpl-install

doc-run: &doc-build
name: Build documentation
command: make O=-W html
command: make html
working_directory: doc

doc-bundle-run: &doc-bundle
Expand Down
2 changes: 1 addition & 1 deletion doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXOPTS = -W
SPHINXBUILD = python -msphinx
SPHINXPROJ = matplotlib
SOURCEDIR = .
Expand Down
21 changes: 14 additions & 7 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,17 +87,24 @@ Other useful invocations include
# Build pdf docs.
make latexpdf

You can build the documentation with several options:
The ``SPHINXOPTS`` variable is set to ``-W`` by default to turn warnings into
errors. To unset it, use

* ``make O=-W html`` turns Sphinx warnings into errors. The continuous
integration script uses this option.
* ``make O=-j4 html`` (for example) runs a parallel build with 4 processes.
.. code-block:: sh

make SPHINXOPTS= html

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.

Multiple options can be combined using e.g. ``make O='-W -j4 ...' html``. On
Windows, the option needs to be set as the ``SPHINXOPTS`` environment
variable, e.g. ``set SPHINXOPTS=-W -j4 & make html``.
Multiple options can be combined using e.g. ``make O='-j4 -Dplot_gallery=0'
html``.

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

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

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
Expand All @@ -26,11 +28,11 @@ if errorlevel 9009 (

if "%1" == "" goto help

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

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

:end
popd