Switch to makefile-based doc build. #9513

anntzer · 2017-10-22T00:59:46Z

PR Summary

My own attempt at switching to make html for docs build.

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

jklymak

This seems to work on my machine. I checked the options that were documented, and they seemed to work. I also checked the built docs and they look fine, though of course I didn't go down each tree.

jklymak · 2017-11-16T20:04:50Z

doc/README.txt

 Matplotlib documentation
 ========================

-


This seems to duplicate documenting_mpl.rst Can all of this just be removed and replaced by reference?

QuLogic · 2017-11-16T20:03:14Z

doc/devel/documenting_mpl.rst


 .. note::

  * You'll need a minimal working LaTeX distribution for many examples to run.
-  * `Graphviz <http://www.graphviz.org/Download.php>`_ is not a python package, and needs
+  * `Graphviz <http://www.graphviz.org/Download.php>`_ is not a python package, and needs 


Unnecessary change?

fixed, dunno how the spare space got there

QuLogic · 2017-11-16T20:05:21Z

doc/devel/release_guide.rst

@@ -54,7 +54,7 @@ temporarily comment out the include and toctree glob; re-instate these after a
 release. Finally, make sure that the docs build cleanly ::

  pushd doc
-  python make.py html latex -n 16
+  make html latexpdf -n$(nproc)


O=-n$(nproc)? Currently, this will build html and latexpdf in parallel, but I'm not sure Sphinx will like two runs occurring in parallel.

Ooops, I didn't check this one. Good eye: that doesn't run at all on my machine.

Glad someone more knowledgeable is reviewing!

Good catch.

I think you only fixed the one below that didn't have this comment. 😛

try again...

QuLogic · 2017-11-16T20:07:30Z

doc/make.bat

+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%


Don't you need to check for sphinx build before running this too?

this should be reported to upstream but I fixed it locally.
(can you do it?)

anntzer · 2017-11-16T20:26:55Z

Comments addressed in force-pushed commit. Thanks for the review.

anntzer · 2017-11-17T00:03:19Z

rebased after the merge of #9311

tacaswell · 2017-11-23T20:39:41Z

doc/Makefile

+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =


Can we default to -W?

I would much prefer not: when building locally I can easily check from the log whether the build failed, but I'd rather not have the build (which can be quite lengthy) fail halfway, fix one error, restart a build, wait another 5min, fix the next error, etc. (Well I know --allowsphinxwarnings, or, on the new system, how to override O=; but I think it's not the most new-contributor friendly way to do it...)
(xref sphinx-doc/sphinx#3627)

The CI runs with it so new contributors are going to have to deal with the failures one way or the other and getting them locally by default seems nicer than having to go through CI

Warnings are perfectly well printed without -W as well, the only effects of -W are that 1) the build stops after the first failure (not so nice for new contribs) and 2) the return status is nonzero in that case (relevant for CI, not so much for new contribs).

I can see both sides, but I guess I think it'd be more confusing to have it build locally and then fail on CI. OTOH it'd be great to have the warning switch very clearly documented so knowledgable users can run that way and then clean all their errors in one compile.

Besides, the current behaviour is to fail on warning by default.

anntzer · 2017-11-23T21:15:16Z

Minor edit to use make -Cdoc ... instead on pushd/popd in the release guide.

QuLogic · 2017-12-01T07:57:59Z

Seems to need a rebase.

anntzer · 2017-12-01T09:14:43Z

fixed

tacaswell · 2017-12-01T14:53:14Z

I prefer to default to fail-on-warning, but will not block the PR over it.

anntzer · 2017-12-02T23:21:24Z

changed to -W by default

jklymak · 2017-12-02T23:55:34Z

doc/make.py

@@ -1,228 +0,0 @@
-#!/usr/bin/env python


OK, this all looks great to me, and it works, and the tests pass, so I think its good to go. But do we need to remove make.py? Someone may have a fancy script that uses it for something and want to keep it around, maybe with a big warning at the beginning that its going away soon?

The converse of that argument is that it might be confusing to have both.

I don't really care, but was just trying to think of what could go wrong.

I don't think we ever made any guarantees as to backcompatibility of tooling (and wouldn't want to do so either).

Even I think we don't need to worry about this too much. The downstream packagers (debian, fedora, etc) will need to adapt their build scripts, but it is clearly documented what to change it too.

tacaswell · 2017-12-03T01:34:21Z

Thanks @anntzer

jklymak · 2017-12-03T01:35:00Z

Yay!

anntzer added the Documentation label Oct 22, 2017

anntzer force-pushed the make-docs branch from a8e0fff to 7046f57 Compare October 22, 2017 05:29

anntzer mentioned this pull request Oct 22, 2017

Update docs on docs. #9311

Merged

6 tasks

anntzer force-pushed the make-docs branch from 7046f57 to a7351a7 Compare November 2, 2017 21:25

dstansby added this to the v2.2 milestone Nov 4, 2017

This was referenced Nov 7, 2017

Moving from make.py to Makefile for sphinx-build #9712

Closed

PR: Port Figure docstrings to numpydoc #9777

Merged

timhoffm mentioned this pull request Nov 14, 2017

Consistent Documentation Guide for Docstrings #9786

Closed

6 tasks

anntzer mentioned this pull request Nov 16, 2017

WIP Update documentating guide #9804

Closed

jklymak approved these changes Nov 16, 2017

View reviewed changes

QuLogic reviewed Nov 16, 2017

View reviewed changes

anntzer force-pushed the make-docs branch from a7351a7 to 913a8e8 Compare November 16, 2017 20:26

anntzer force-pushed the make-docs branch 2 times, most recently from 7e8ccbc to 3438f84 Compare November 17, 2017 00:02

tacaswell reviewed Nov 23, 2017

View reviewed changes

anntzer force-pushed the make-docs branch from 3438f84 to eaf3f9e Compare November 23, 2017 21:14

anntzer mentioned this pull request Nov 30, 2017

DOC: re-organize devel/documenting_mpl.rst #9884

Merged

Switch to makefile-based doc build.

8886a19

anntzer force-pushed the make-docs branch from eaf3f9e to 8886a19 Compare December 1, 2017 09:14

Default to -W.

b4b1f64

jklymak reviewed Dec 2, 2017

View reviewed changes

tacaswell merged commit 5392f2e into matplotlib:master Dec 3, 2017

anntzer deleted the make-docs branch December 3, 2017 01:36

anntzer mentioned this pull request Dec 3, 2017

Use Makefile for sphinx build #5798

Closed

timhoffm mentioned this pull request Dec 9, 2017

The documentation on "how to write documentation" need to be updated #7217

Closed

QuLogic modified the milestones: needs sorting, v2.2.0 Feb 12, 2018

anntzer mentioned this pull request Apr 26, 2018

Some changes in make.bat and the build documentation documentation #11121

Closed

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Switch to makefile-based doc build. #9513

Switch to makefile-based doc build. #9513

anntzer commented Oct 22, 2017

jklymak left a comment

jklymak Nov 16, 2017

anntzer Nov 16, 2017

QuLogic Nov 16, 2017

anntzer Nov 16, 2017

QuLogic Nov 16, 2017

jklymak Nov 16, 2017

anntzer Nov 16, 2017

QuLogic Nov 16, 2017

anntzer Nov 16, 2017

QuLogic Nov 16, 2017

anntzer Nov 16, 2017 •

edited

Loading

anntzer commented Nov 16, 2017

anntzer commented Nov 17, 2017

tacaswell Nov 23, 2017

anntzer Nov 23, 2017

tacaswell Nov 25, 2017

anntzer Nov 25, 2017

jklymak Dec 2, 2017

anntzer commented Nov 23, 2017

QuLogic commented Dec 1, 2017

anntzer commented Dec 1, 2017

tacaswell commented Dec 1, 2017

anntzer commented Dec 2, 2017

jklymak Dec 2, 2017

anntzer Dec 3, 2017

tacaswell Dec 3, 2017

tacaswell commented Dec 3, 2017

jklymak commented Dec 3, 2017

Switch to makefile-based doc build. #9513

Switch to makefile-based doc build. #9513

Conversation

anntzer commented Oct 22, 2017

PR Summary

PR Checklist

jklymak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anntzer Nov 16, 2017 • edited Loading

Choose a reason for hiding this comment

anntzer commented Nov 16, 2017

anntzer commented Nov 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anntzer commented Nov 23, 2017

QuLogic commented Dec 1, 2017

anntzer commented Dec 1, 2017

tacaswell commented Dec 1, 2017

anntzer commented Dec 2, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Dec 3, 2017

jklymak commented Dec 3, 2017

anntzer Nov 16, 2017 •

edited

Loading