Resurrecting axes_grid1 documentation #11079

ImportanceOfBeingErnest · 2018-04-18T16:17:52Z

PR Summary

This is an attempt to resurrect the axes_grid1 and axisartist documentation.
Those are not present in the current docs, see #9582

The strategy here is to move stuff from
doc/mpl_toolkits/ → doc/api/toolkits
and create a toc for both modules.

Then, a lot of broken links need to be replaced.

Currently this still fails due to mpl_toolkits.axes_grid1.colorbar.colorbar not producing a valid docstring.
There are also a couple of missing files which should be produced by sphinx-gallery, but are not for some reason. (solved)

~~I will try to include the make.bat into this PR without -W flag, such that the tests can hopefully build the docs and people can look at the produced errors.~~ (solved)

The general idea here would be:

create a working documentation for axisartist and axes_grid1 inside of doc/api/toolkits first.
As can be seen, this is unproblematic in general, but causes some trouble with broken docstrings and missing files etc. Those have now been solved. In particular:
- problematic links have been replaced by the full version (~matplotlib.axes.Axes instead of .Axes)
- classes for which no examples are created by sphinx-gallery (No examples file generates for aliases sphinx-gallery/sphinx-gallery#365) are excluded inside the template.
- The offending colorbar vs Colorbar issue (autodoc&autosummary fails for uppercase/lowercase class/function sphinx-doc/sphinx#4874) has been worked around by using a different template for this special case.
Now that those problems are solved and a valid documentation can be built, one may in a next step move it outside of doc/api - in case this is still desired. (I didn't manage to do this, so I would propose to do this in a new PR if someone has a solution to that).

PR Checklist

Code is PEP 8 compliant
Documentation is sphinx and numpydoc compliant

jklymak · 2018-04-18T16:23:06Z

marked as WIP, since I imagine this isn't ready for review yet?

It seems we shouldn't have to change the doc tree to get this to work, but I've not looked too carefully. It seemed to me that the index.rst for doc/mpl_toolkits/axes_grid/index.rst just wasn't formatted in a modern way. But I didn't get to the point of testing so I could be wrong.

ImportanceOfBeingErnest · 2018-04-18T16:30:31Z

This is not yet ready for review in the sense of a working code; and I suppose tests will fail. But the docs can be built without -W flag, i.e. SPHINXOPTS=. In that sense, if anyone wants to comment on this, they should.

The problem of keeping the doc/mpl_toolkits is that what is in there can hardly be synchronized with the rest of the docs. While if you put it into doc/api/... it can live there without problem.

dstansby · 2018-04-18T16:31:22Z

tutorials/text/text_intro.py

@@ -38,17 +38,20 @@
 `.pyplot` API       OO API              description
 =================== =================== ======================================
 `~.pyplot.text`     `~.Axes.text`       Add text at an arbitrary location of
-                                        the `.Axes`.
+                                        the `~matplotlib.axes.Axes`.


You should be able to do ~.axes.Axes that saves a bit of space (and similarly for the changes below)

Probably. But due to three different Axes being around I wanted to be on the safe side first. ;-)

Umm, OK, so does this change break the simple .Axes shortcut? If so, I'm a little leery about accepting it, because I can't imagine there aren't other places in the code where this shortcut has been used then the ones you've flagged above....

ImportanceOfBeingErnest · 2018-04-19T15:05:24Z

The problem about missing files seems to be due to sphinx-gallery not creating .examples files for aliased classes. I opened issue sphinx-gallery/sphinx-gallery#365 over there.

ImportanceOfBeingErnest · 2018-04-19T15:13:03Z

The colorbar problem is however a real mystery. If I rename the mpl_toolkits.axes_grid1.colorbar.colorbar method to donaldduck, the respective doc page are created without problem (this just breaks some of the examples of course).

ImportanceOfBeingErnest · 2018-04-20T21:52:01Z

The last blocker here is that it is apparently not possible to get an autodoc/autosummary documentation created for a file that contains a class and a function of the same name, one uppercase, one lowercase.

class Colorbar():
      # ...

def colorbar():
     # ...

I opened this issue sphinx-doc/sphinx#4874 about it.

anntzer · 2018-04-20T22:59:29Z

I bet the issue will be closed as wontfix on sphinx, as it's a fundamental problem of the Windows FS (that it doesn't distinguish (*modulo really low-level hacks) files differing only based case; and any fix I can think of would involve breaking the correspondence [pythonname] -> [pythonname.rst] -> [pythonname.html], which seems to be quite a big price to pay).

Looks like the stuff builds fine on circleci, so that's good enough for me (but leaving open for now in case anyone wants to comment on the above).

anntzer · 2018-04-20T23:01:24Z

doc/_templates/autosummary.rst

@@ -6,11 +6,14 @@
 .. auto{{ objtype }}:: {{ objname }}

 {% if objtype in ['class', 'method', 'function'] %}
+{% if objname not in ['AxesGrid', 'Scalable', 'HostAxes', 'FloatingAxes',
+                      'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}


I assume the plan is to remove these after their docstrings are fixed? Perhaps leave a comment to that effect.

This relates to sphinx-gallery/sphinx-gallery#365; so yes, once that is fixed, one can remove.

anntzer · 2018-04-20T23:01:56Z

doc/api/toolkits/axes_grid.rst

-   axes_grid1
-   axisartist
+
+:ref:`toolkit_axisartist-index`


what happened here?

confused now

anntzer · 2018-04-20T23:03:06Z

doc/make.bat

@@ -10,7 +10,7 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=.
 set BUILDDIR=build
 set SPHINXPROJ=matplotlib
-set SPHINXOPTS=-W
+set SPHINXOPTS=


needs to come back

Sure. I just need this for testing locally.

You can do make html "SPHINXOPTS=" to override the -W flag locally I think.

ImportanceOfBeingErnest · 2018-04-20T23:24:22Z

@anntzer I doubt the version as it is now will be the version going in. I wanted to share the current progress because I got stuck at several places and thought maybe someone has a good idea.

Now it seems that it finally passes the test on the server. 🎉
But I cannot build the docs correctly on windows. Not sure in how far this is a blocker, like "You can build the docs only on linux." is not really statisfactory, right?

The next thing to look at is of course how the toolkits should finally look like. Feedback and suggestions are welcome.
This is the current version.

Should there be a list as it is now?
Should the axes_grid disappear completely in favour of axes_grid1 and axisartist?

anntzer · 2018-04-20T23:29:44Z

What do you get on Windows? A complete failure to build (even removing -W from sphinxopts), or just something wrong wrt colorbar links?
If the latter, I wouldn't consider that a blocker because solving casefolding issues on Windows is well beyond what Matplotlib should be worried about (see e.g. the issues for git and mercurial on that same topic). If the former I'd be more agreeable to waiting for a fix.

jklymak · 2018-04-20T23:31:16Z

After the config changes get reverted, this is great. Great job @ImportanceOfBeingErnest this is a huge improvement!

ImportanceOfBeingErnest · 2018-04-20T23:39:03Z

Without -W flag, i.e. turning errors into warnings, you get a lot of red lines in the console when building but the output is fine, except for the .colorbar module and any links to or from it.
In that sense maybe you're right and one would just have to include a sentence about removing -W on the page about building the docs on windows.

ImportanceOfBeingErnest · 2018-04-20T23:41:59Z

I will try to get a good version of this together tomorrow - there is still a lot of pieces to glue together.

anntzer · 2018-04-20T23:43:10Z

I would just remove the -W from make.bat then, with a comment explaining why.

To be clear, I think Windows support is just as important as Linux/OSX (see #3148 for literally my first issue (not PR) on this repo), but the specific issue at hand is so complex that it's just not worth blocking on it.

ImportanceOfBeingErnest · 2018-04-21T14:03:07Z

I think I found an acceptable workaround, not using the autosummary for the colorbar docs at all. This allows to keep the -W flag.

I think this should now be ready for review.

jklymak

Seems fine, but its certainly a bit of a discussion item that now .Axes doesn't work, and folks will have to remember to disambiguate it...

jklymak · 2018-04-21T21:24:14Z

lib/matplotlib/pyplot.py


    If *nrows*, *ncols* and *index* are all less than 10, they can also be
    given as a single, concatenated, three-digit number.

    For example, ``subplot(2, 3, 3)`` and ``subplot(233)`` both create an
-    `.Axes` at the top right corner of the current figure, occupying half of
-    the figure height and a third of the figure width.
+    `matplotlib.axes.Axes` at the top right corner of the current figure,


In future, it'd be nicer if changes like this that are orthogonal to the main PR are put in a separate PR. Did you need to do these to get the docs to build or something?

jklymak · 2018-04-21T21:26:46Z

tutorials/intermediate/constrainedlayout_guide.py

-# represents the outside of the Axes and all its decorations (i.e. ticklabels,
-# axis labels, etc.).  The second layoutbox corresponds to the Axes'
-# `ax.position`, which sets where in the figure the spines are placed.
+# Each ``~matplotlib.axes.Axes` has *two* layoutboxes.  The first one,


Again, why did you change these? The original worked just fine in the main docs... https://matplotlib.org/tutorials/intermediate/constrainedlayout_guide.html#sphx-glr-tutorials-intermediate-constrainedlayout-guide-py

jklymak · 2018-04-21T21:28:34Z

tutorials/text/text_intro.py

@@ -38,17 +38,20 @@
 `.pyplot` API       OO API              description
 =================== =================== ======================================
 `~.pyplot.text`     `~.Axes.text`       Add text at an arbitrary location of
-                                        the `.Axes`.
+                                        the `~matplotlib.axes.Axes`.


Umm, OK, so does this change break the simple .Axes shortcut? If so, I'm a little leery about accepting it, because I can't imagine there aren't other places in the code where this shortcut has been used then the ones you've flagged above....

jklymak · 2018-04-21T21:31:37Z

Milestoning 3.0, but happy for it to be back ported if possible...

ImportanceOfBeingErnest · 2018-04-21T22:29:29Z

Yes, .Axes wont work any more. But I suppose ~.axes.Axes would (as commented by @dstansby). I could change them all to ~.axes.Axes if people want that.
I did change all occurences, so you don't need to be afraid of that. Essentially if we keep the -W flag active, that will be an automatic test. If someone puts ~.Axes somewhere the doc built would fail with a rather self-explanatory error in how far this is ambiguous. (Unfortunately the error will tell you the line in the rst file, not the python file where this happens, so one might need to search for a bit to find the offending line.)

jklymak

Thanks so much for tracking this down. Its been a big hole in the docs for a while!

ImportanceOfBeingErnest · 2018-05-03T17:26:41Z

@tacaswell This is the PR I was refering to, which revives the axes_grid1 and axisartist documentation. The respective docs had been present in v2.0.2 see e.g. this page

But then it has disappeared, such that the current 2.2.2 version looks pretty empty.

This PR has revived the documentation. In that sense it fixes a regression. One could therefore argue that it should be backported.
Of course one could also argue that it is non-critical because there is still the 2.0.2 version available from the internet in case people need it.

tacaswell · 2018-06-05T00:42:14Z

@meeseeksdev backport to v2.2.x

lumberbot-app · 2018-06-05T00:42:37Z

There seem to be a conflict, please backport manually

tacaswell · 2018-06-05T00:42:52Z

This can't go back to 2.2.2-doc due to the changes to the source files, lets see if it backports cleanly...

…rrect-axesgrid1-doc DOC: Resurrecting axes_grid1 documentation Conflicts: lib/matplotlib/figure.py - kept master branch version of a docstring lib/mpl_toolkits/axes_grid1/colorbar.py - conflicts around __future__ import lib/mpl_toolkits/axisartist/axis_artist.py - conflicts around __future__ import

jklymak added the status: work in progress label Apr 18, 2018

dstansby reviewed Apr 18, 2018

View reviewed changes

ImportanceOfBeingErnest force-pushed the resurrect-axesgrid1-doc branch from 68ade78 to dd7493a Compare April 18, 2018 16:44

This was referenced Apr 18, 2018

axes_grid1 docs do not appear on mpl.org anymore. #9582

Closed

No examples file generates for aliases sphinx-gallery/sphinx-gallery#365

Open

ImportanceOfBeingErnest force-pushed the resurrect-axesgrid1-doc branch 2 times, most recently from 6b8fa6b to 4f56e81 Compare April 20, 2018 21:49

ImportanceOfBeingErnest force-pushed the resurrect-axesgrid1-doc branch from 4f56e81 to d2758fd Compare April 20, 2018 22:18

anntzer previously approved these changes Apr 20, 2018

View reviewed changes

anntzer reviewed Apr 20, 2018

View reviewed changes

doc/api/toolkits/axes_grid.rst Outdated

axes_grid1

axisartist

:ref:`toolkit_axisartist-index`

Copy link

Contributor

anntzer Apr 20, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what happened here?

anntzer reviewed Apr 20, 2018

View reviewed changes

ImportanceOfBeingErnest force-pushed the resurrect-axesgrid1-doc branch from d2758fd to f410859 Compare April 21, 2018 14:00

jklymak reviewed Apr 21, 2018

View reviewed changes

jklymak added the Documentation label Apr 21, 2018

jklymak added this to the v3.0 milestone Apr 21, 2018

ImportanceOfBeingErnest changed the title ~~Attempt to resurrect axes_grid1 documentation~~ Resurrecting axes_grid1 documentation Apr 21, 2018

jklymak removed the status: work in progress label Apr 21, 2018

jklymak approved these changes Apr 21, 2018

View reviewed changes

jklymak added the status: needs review label Apr 28, 2018

ImportanceOfBeingErnest force-pushed the resurrect-axesgrid1-doc branch from 801d0ed to 7929480 Compare April 30, 2018 19:35

resurrect axes_grid1 doc

1a9729e

ImportanceOfBeingErnest force-pushed the resurrect-axesgrid1-doc branch from 7929480 to 1a9729e Compare April 30, 2018 20:34

tacaswell merged commit 448ba7d into matplotlib:master May 1, 2018

QuLogic removed the status: needs review label May 1, 2018

tacaswell modified the milestones: v3.0, v2.2-doc, v2.2.3 Jun 5, 2018

lumberbot-app bot added the status: needs manual backport label Jun 5, 2018

ImportanceOfBeingErnest mentioned this pull request Aug 5, 2018

Fix inset_axes + doc #11060

Merged

5 tasks

tacaswell mentioned this pull request Aug 5, 2018

Backport axes grid work #11813

Merged

tacaswell removed the status: needs manual backport label Aug 10, 2018

thomasjpfan mentioned this pull request Dec 10, 2018

Documentation paths are ambiguous on case insensitive file systems scikit-learn/scikit-learn#12712

Closed

ImportanceOfBeingErnest deleted the resurrect-axesgrid1-doc branch February 17, 2019 23:16

anntzer mentioned this pull request Apr 19, 2023

[MNT]: Run docs CI build with O=-Dmissing_references_write_json=1 and print out missing_references.json #25725

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Resurrecting axes_grid1 documentation #11079

Resurrecting axes_grid1 documentation #11079

ImportanceOfBeingErnest commented Apr 18, 2018 •

edited

Loading

jklymak commented Apr 18, 2018

ImportanceOfBeingErnest commented Apr 18, 2018

dstansby Apr 18, 2018

ImportanceOfBeingErnest Apr 18, 2018

jklymak Apr 21, 2018

ImportanceOfBeingErnest commented Apr 19, 2018

ImportanceOfBeingErnest commented Apr 19, 2018 •

edited

Loading

ImportanceOfBeingErnest commented Apr 20, 2018

anntzer commented Apr 20, 2018 •

edited

Loading

anntzer Apr 20, 2018

ImportanceOfBeingErnest Apr 20, 2018

anntzer Apr 20, 2018

anntzer Apr 20, 2018

ImportanceOfBeingErnest Apr 20, 2018

dstansby Apr 21, 2018

ImportanceOfBeingErnest commented Apr 20, 2018

anntzer commented Apr 20, 2018

jklymak commented Apr 20, 2018

ImportanceOfBeingErnest commented Apr 20, 2018

ImportanceOfBeingErnest commented Apr 20, 2018

anntzer commented Apr 20, 2018

ImportanceOfBeingErnest commented Apr 21, 2018

jklymak left a comment

jklymak Apr 21, 2018

jklymak Apr 21, 2018

jklymak Apr 21, 2018

jklymak commented Apr 21, 2018

ImportanceOfBeingErnest commented Apr 21, 2018 •

edited

Loading

jklymak left a comment

ImportanceOfBeingErnest commented May 3, 2018

tacaswell commented Jun 5, 2018

lumberbot-app bot commented Jun 5, 2018

tacaswell commented Jun 5, 2018

Resurrecting axes_grid1 documentation #11079

Resurrecting axes_grid1 documentation #11079

Conversation

ImportanceOfBeingErnest commented Apr 18, 2018 • edited Loading

PR Summary

PR Checklist

jklymak commented Apr 18, 2018

ImportanceOfBeingErnest commented Apr 18, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ImportanceOfBeingErnest commented Apr 19, 2018

ImportanceOfBeingErnest commented Apr 19, 2018 • edited Loading

ImportanceOfBeingErnest commented Apr 20, 2018

anntzer commented Apr 20, 2018 • edited Loading

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

ImportanceOfBeingErnest commented Apr 20, 2018

anntzer commented Apr 20, 2018

jklymak commented Apr 20, 2018

ImportanceOfBeingErnest commented Apr 20, 2018

ImportanceOfBeingErnest commented Apr 20, 2018

anntzer commented Apr 20, 2018

ImportanceOfBeingErnest commented Apr 21, 2018

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

jklymak commented Apr 21, 2018

ImportanceOfBeingErnest commented Apr 21, 2018 • edited Loading

jklymak left a comment

Choose a reason for hiding this comment

ImportanceOfBeingErnest commented May 3, 2018

tacaswell commented Jun 5, 2018

lumberbot-app bot commented Jun 5, 2018

tacaswell commented Jun 5, 2018

ImportanceOfBeingErnest commented Apr 18, 2018 •

edited

Loading

ImportanceOfBeingErnest commented Apr 19, 2018 •

edited

Loading

anntzer commented Apr 20, 2018 •

edited

Loading

ImportanceOfBeingErnest commented Apr 21, 2018 •

edited

Loading