Cleanup doc/conf.py & local sphinx extensions #9708

anntzer · 2017-11-06T23:05:47Z

Split out extensions to their own files.

Emit the latex symbol tables without breaks.

PR Summary

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

tacaswell · 2017-11-07T04:43:43Z

doc/sphinxext/gen_rst.py

@@ -1,173 +0,0 @@
-"""


I am concerned that someone is depending on this. There is not much harm in carrying this file.

On second thought, was this even importable outside of our docs build? 🐑

The importable stuff is in lib/matplotlib/sphinxext.

tacaswell · 2017-11-07T04:53:21Z

👍 conditional on gen_rst not being importable by anyone else.

anntzer · 2017-11-07T05:02:24Z

I can't see how it would be. For example it is not included in a (default) wheel.
(Note that the conf.py explicitly has

# If your extensions are in another directory, add it here. If the directory
# is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
sys.path.append(os.path.abspath('.'))

which is what made it importable in the docs build.)

jenshnielsen · 2017-11-07T10:01:11Z

doc/conf.py

+    'matplotlib.sphinxext.plot_directive',
+    'sphinxext.github',
+    'sphinxext.math_symbol_table',
+    'sphinxext.mock_gui_toolkits',


If we drop support for sphinx older than 1.3 we can probably replace this with the build in autodoc_mock_imports in http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_mock_imports If we drop versions below 1.6 we can make it simpler by only mocking the top level modules. As I recall it I added the mocking here predates Sphinx 1.3 which is why its done manually

What is the argument for not requiring 1.6?

The only one I can think of is building with Sphinx from apt-get/yum but I am not sure we need to support that

I think debian does build our docs as part of the build process. @sandrotosi How much pain would it cause you to bump to sphinx 1.6?

it would be no problem at all, actually it would be really helpful as in Debian we're migrating to sphinx 1.6 and the current doc cannot be built with that version, so thanks for pushing to use 1.6 :)

nope, what i really should do is updating matplotlib in debian (which i'll do as soon as i find time for it)

I don't think that's going to work because we need some mocked objects to be types (so that we can subclass them) or callables with specific return values (sip.getapi), rather than just "existing" (in other words, because we are running code at the toplevel rather than just defining a bunch of functions).

Debian 7 “Wheezy” is still supported (https://wiki.debian.org/LTS) and it has 1.1.3 sphinx (https://packages.debian.org/search?keywords=python-sphinx) =\

TBH i wouldnt worry about wheezy (nor jessie) - if anyone will want to get an updated mpl on that release, they'll have to take care of backporting a tons of other deps (numpy in primis) before caring about sphinx and missing documentation

True, but even stretch does not have 1.6

anntzer · 2017-11-07T19:22:40Z

I think the mocking would be better resolved in a separate PR that strips out all the backend_foo individual doc pages (which are incomplete anyways) in favor of a single, hand-written doc for all the backends that lists the common public API of all backends.

anntzer · 2018-01-01T00:04:22Z

Also got rid of the mpl_examples symlink, which is now unneeded.

QuLogic · 2018-01-09T01:39:51Z

A tangentially related request; can you move the sphinx_gallery import to after check_deps so sphinx doesn't fail with an import error instead of our proper error message?

anntzer · 2018-01-09T03:13:46Z

done

jklymak · 2018-01-19T17:40:48Z

This needs a rebase and tests to pass....

anntzer · 2018-01-20T10:37:16Z

done (well, OSX is backlogged...)

timhoffm · 2018-02-03T16:39:44Z

doc/conf.py

-# Use IPython's console highlighting by default
-extensions.extend(['IPython.sphinxext.ipython_console_highlighting',
-                   'IPython.sphinxext.ipython_directive'])
+from sphinx_gallery.sorting import ExplicitOrder


Why move the import from the head of the file here?

#9708 (comment)

Thanks. IMO this could use a short comment.

timhoffm · 2018-02-03T16:49:13Z

doc/devel/documenting_mpl.rst

-This is rendered as :doc:`/tutorials/introductory/customizing` (see the
-bottom of the page.  Note that this is in a tutorial;  See
-:ref:`writing-examples-and-tutorials` below)
+This is rendered as at the bottom of


timhoffm · 2018-02-03T16:52:15Z

doc/devel/documenting_mpl.rst

-reference when the documentation is built.
+Note that the python script that generates the plot is referred to, rather than
+any plot that is created; sphinx-gallery will provide the correct reference
+when the documentation is built.


I would leave the . instead of the ;

QuLogic · 2018-02-04T20:07:37Z

Needs a rebase now, too.

anntzer · 2018-02-06T08:16:16Z

done

Emit the latex symbol tables without breaks.

anntzer added the Documentation label Nov 6, 2017

anntzer force-pushed the confpy branch 4 times, most recently from 08d3351 to cf0106d Compare November 6, 2017 23:27

tacaswell reviewed Nov 7, 2017

View reviewed changes

tacaswell added this to the v2.2 milestone Nov 7, 2017

tacaswell approved these changes Nov 7, 2017

View reviewed changes

jenshnielsen reviewed Nov 7, 2017

View reviewed changes

anntzer force-pushed the confpy branch from cf0106d to 36043ff Compare November 7, 2017 19:23

anntzer mentioned this pull request Nov 17, 2017

Backend switching #9795

Closed

anntzer mentioned this pull request Dec 31, 2017

Remove gen rst #10137

Merged

anntzer force-pushed the confpy branch from 36043ff to a5ba245 Compare December 31, 2017 23:53

anntzer force-pushed the confpy branch from a5a0adc to 84be143 Compare January 9, 2018 03:13

anntzer mentioned this pull request Jan 11, 2018

Additional docstring recommendations #10225

Closed

anntzer force-pushed the confpy branch 2 times, most recently from ae39a7a to 9597c9a Compare January 20, 2018 09:31

timhoffm reviewed Feb 3, 2018

View reviewed changes

anntzer force-pushed the confpy branch 2 times, most recently from 55ce5fd to 8f4fd73 Compare February 6, 2018 08:16

anntzer added 2 commits February 6, 2018 09:28

Cleanup doc/conf.py.

de81397

Emit the latex symbol tables without breaks.

Get rid of the mpl_examples symlink.

734a189

anntzer force-pushed the confpy branch from 8f4fd73 to 734a189 Compare February 6, 2018 08:28

timhoffm merged commit b7d87d9 into matplotlib:master Feb 6, 2018

anntzer deleted the confpy branch February 6, 2018 18:26

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

tacaswell mentioned this pull request Apr 30, 2018

Remove mpl_examples symlink. #11141

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cleanup doc/conf.py & local sphinx extensions #9708

Cleanup doc/conf.py & local sphinx extensions #9708

anntzer commented Nov 6, 2017 •

edited

Loading

tacaswell Nov 7, 2017

tacaswell Nov 7, 2017

QuLogic Nov 7, 2017

tacaswell commented Nov 7, 2017

anntzer commented Nov 7, 2017

jenshnielsen Nov 7, 2017

tacaswell Nov 7, 2017

jenshnielsen Nov 7, 2017

tacaswell Nov 7, 2017

sandrotosi Nov 7, 2017

sandrotosi Nov 7, 2017

anntzer Nov 7, 2017

Kojoley Nov 11, 2017

sandrotosi Nov 11, 2017

Kojoley Nov 11, 2017

anntzer commented Nov 7, 2017

anntzer commented Jan 1, 2018

QuLogic commented Jan 9, 2018

anntzer commented Jan 9, 2018

jklymak commented Jan 19, 2018

anntzer commented Jan 20, 2018

timhoffm Feb 3, 2018

QuLogic Feb 3, 2018

timhoffm Feb 3, 2018

anntzer Feb 6, 2018

timhoffm Feb 3, 2018

timhoffm Feb 3, 2018

QuLogic commented Feb 4, 2018

anntzer commented Feb 6, 2018

Cleanup doc/conf.py & local sphinx extensions #9708

Cleanup doc/conf.py & local sphinx extensions #9708

Conversation

anntzer commented Nov 6, 2017 • edited Loading

PR Summary

PR Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Nov 7, 2017

anntzer commented Nov 7, 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

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 7, 2017

anntzer commented Jan 1, 2018

QuLogic commented Jan 9, 2018

anntzer commented Jan 9, 2018

jklymak commented Jan 19, 2018

anntzer commented Jan 20, 2018

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

QuLogic commented Feb 4, 2018

anntzer commented Feb 6, 2018

anntzer commented Nov 6, 2017 •

edited

Loading