Reorganise mpl_toolkits documentation #5752

jenshnielsen · Dec 26, 2015

The mpl_toolkits axes_grid and axisartist documentation is very focused on the axes_grid namespace dispite the fact that this is not recommenced for use. The code has been split into axes_grid1 and axisartist. This PR aims to do the same for the documentation and make the documentation more visible and consistent.

Move related packages that we don't ship to external resources
Reorganise axes_grid documentation to split in axes_grid1 and axisartist
Split examples and figures into 2 folders.
Move the documentation up one level in the toc to make it more obvious where the toolkit documentation is.

This is WIP because the text still needs some editing for consistency. A tiny bit of functionality is still hidden in axes_grid.parasiteaxis which I plan to more to axesartist.

I am also tempted to move deprecate axes_grid and interested in input to this.

The docs as build by this branch is up at http://jenshnielsen.github.io/matplotlib

tacaswell · Dec 28, 2015

I am not a fan of putting the external toolkits under the same top-level heading. Maybe add a top-level "Third-party toolkits" section?

jenshnielsen · Dec 28, 2015

I not quite sure what you mean. Are you suggesting to move the page from External Resources to a separate top level heading? That makes sense to me.

tacaswell · Dec 28, 2015

Yes, something like:

 - external resources
 - MPL API
 - Toolkits
    - axes_gird1
    - mplot3d
    - 
 - Third-party extensions packages
    - trendvis
    - seaborn
    - ..

jenshnielsen · Dec 28, 2015

👍

jenshnielsen · Dec 29, 2015

I think this should be ready for review. The branch at http://jenshnielsen.github.io/matplotlib is updated with the result of building 156cb7f

WeatherGod · Dec 29, 2015

Uhm, pretty sure this isn't the result of your changes, but the logo/banner
at the top of the homepage is completely messed up for me. The text of
"matplotlib" is too large causing the "m" and the "b" to be cut off on
either end the radar chart logo to be right on top of it.

Using Firefox 43 on Ubuntu.

On Tue, Dec 29, 2015 at 9:12 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:

I think this should be ready for review. The branch at
http://jenshnielsen.github.io/matplotlib is updated with the result of
building 156cb7f
156cb7f

—
Reply to this email directly or view it on GitHub
#5752 (comment)
.

jenshnielsen · Dec 29, 2015

@WeatherGod Is that any different from http://matplotlib.org/devdocs/?

WeatherGod · Dec 29, 2015

No, it is the same on both pages.

On Tue, Dec 29, 2015 at 9:41 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:

@WeatherGod https://github.com/WeatherGod Is that any different from
http://matplotlib.org/devdocs/?

—
Reply to this email directly or view it on GitHub
#5752 (comment)
.

jenshnielsen · Dec 29, 2015

It's probably due to #5653 then?

WeatherGod · Dec 29, 2015

as for the mpl_toolkits page itself:
http://jenshnielsen.github.io/matplotlib/mpl_toolkits/index.html, it feels
like there is too much redundant stuff. For example, there is the "mplot3d"
section header, then there is the "mplot3d" bullet point, and then the
"Matplotlib mplot3d toolkit" sub-bullet point. The axes_grid1 and
axisartist stuff isn't too bad, but still feels a little redundant.

On Tue, Dec 29, 2015 at 9:12 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:

I think this should be ready for review. The branch at
http://jenshnielsen.github.io/matplotlib is updated with the result of
building 156cb7f
156cb7f

—
Reply to this email directly or view it on GitHub
#5752 (comment)
.

WeatherGod · Dec 29, 2015

Most likely, I have posted a comment there.

On Tue, Dec 29, 2015 at 9:44 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:

It's probably due to #5653
#5653 then?

—
Reply to this email directly or view it on GitHub
#5752 (comment)
.

jenshnielsen · Dec 29, 2015

@WeatherGod I agree that it's a bit redundant but I have not actually changed that around. That is as it has always been.

jenshnielsen · Dec 29, 2015

But perhaps we should just remove all the TOCs from that page?

Needs .

Would it make sense to link to https://github.com/matplotlib here, since we are encouraging most third-party packages to come under our gh organization?

uses a special -> uses special

artist associated -> associated artist

have -> has

to draw axis -> to draw the 4 axis sides

mdboom · Dec 29, 2015

Oops -- sorry, I missed that this is still a WIP and the text hasn't been edited. I'll hold off on my grammatical/typographical nitpicks until that's done.

jenshnielsen · Dec 29, 2015

Is not WIP any more but by the looks of it most of the typos are in the original text which I have just moved.

mdboom · Dec 29, 2015

I see. Should we try to fix those now anyway? I'm happy to just do them as a PR against this one if that's more efficient...

jenshnielsen · Dec 29, 2015

We might as well fix obvious typos now. I have tried not to do to many heavy edits but most of the examples could definitely need an edit but the question is how much effort we want to put into this part of the code?

mdboom · Dec 29, 2015

I'll spend a few minutes (but no more) fixing obvious typos and submit a PR against this one...

mdboom · Dec 29, 2015

Actually, now that I'm understanding the size of this better, I think it's probably best to leave the text as-is for this PR and try to clean it up later. (We really need to devote some real effort to editing the docs for grammar/consistency in a lot of places...)

jenshnielsen · Dec 30, 2015

@WeatherGod I have removed the toc trees

@mdboom I corrected the typos that you already noted and added a note above the matplotlib organization to thirdpartypackages/index

jenshnielsen · Dec 30, 2015

I have added an api changes noted that axes_grid is deprecated.

The few files which were different in axes_grid have been copied to axisartist
They are mainly Axes from axes_grid but using axisartist axis. This should really be refactored away to make the Axes take an axis type on construction.

WeatherGod · Dec 30, 2015

Has the github.io been updated for the latest changes?

On Wed, Dec 30, 2015 at 7:46 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:

I have added an api changes noted that axes_grid is deprecated.

The few files which were different in axes_grid have been copied to
axisartist
They are mainly Axes from axes_grid but using axisartist axis. This
should really be refactored away to make the Axes take an axis type on
construction.

—
Reply to this email directly or view it on GitHub
#5752 (comment)
.

jenshnielsen · Dec 30, 2015

Sorry I was on a flaky internet connection on the train should be there now

WeatherGod · Dec 30, 2015

looking much better now.

On Wed, Dec 30, 2015 at 11:36 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:

Sorry I was on a flaky internet connection on the train should be there now

—
Reply to this email directly or view it on GitHub
#5752 (comment)
.

jenshnielsen · Jan 4, 2016

Rebased onto current master

jenshnielsen · Jan 5, 2016

I have uploaded a new preview version to http://jenshnielsen.github.io/matplotlibdocs rather than http://jenshnielsen.github.io/matplotlib

jenshnielsen · Jan 5, 2016

I think this should be ready to go. The documentation is by no means perfect but I think this is a significant structural improvement.

"fund" --> "found"

jenshnielsen · Jan 5, 2016

By the way. I'm happy to revet the deprecation of axes_grid and just change the docs in this PR

"axisgrid1"?

Good catch that is embarrassing

uses --> using

WeatherGod · Jan 5, 2016

I think that's all the typos I can find. I vote for deprecation of axes_grid. It has been a long time coming, and splitting axisartist out in the documentation makes things a lot more understandable.

WeatherGod · Jan 5, 2016

This has a +1 from me. Should this be backported to v2.x or should it stay in master?

jenshnielsen · Jan 8, 2016

I was not planning to backport it to 2.x but I can be convinced otherwise. Any objections to merging this. It moves around a large number of examples so I would like to merge it before it acquires to many conflicts.

WeatherGod · Jan 8, 2016

ok, we will leave it in master for now

tacaswell added the needs_review label Dec 26, 2015

jenshnielsen referenced this pull request Dec 29, 2015
Closed
Several axes_grid1 and axisartist examples broken on master #5757

jenshnielsen changed the title from [WIP] Reorganise mpl_toolkits documentation to Reorganise mpl_toolkits documentation Dec 29, 2015

jenshnielsen referenced this pull request Jan 2, 2016
Merged
De-randomize doc builds #5769

WeatherGod added a commit that referenced this pull request Jan 8, 2016

WeatherGod Merge pull request #5752 from jenshnielsen/axisgriddocs
Reorganise mpl_toolkits documentation
5eec831

tacaswell removed the needs_review label Jan 8, 2016

jenshnielsen deleted the jenshnielsen:axisgriddocs branch Jan 8, 2016

QuLogic modified the milestone: next major release (2.0), proposed next point release (2.1) Jan 8, 2016

QuLogic added a commit to QuLogic/matplotlib that referenced this pull request Oct 19, 2016

QuLogic DOC: Remove duplicate documentation from last merge.
These entries were moved from mpl_toolkits to thirdpartpackages on master as part of #5752.
846279e

QuLogic added a commit to QuLogic/matplotlib that referenced this pull request Oct 19, 2016

QuLogic DOC: Remove duplicate documentation from last merge.
These entries were moved from mpl_toolkits to thirdpartypackages on master as part of #5752.
6595e4c

This was referenced Oct 19, 2016

Merged

DOC: Remove duplicate documentation from last merge. #7304

Open

[WIP] Axisartist testing + bugfixes #7545

       </p>
+    +<h1>Third party packages</h1>
+    +
+    +<p>A large number of third party <a href="{{ pathto('mpl_toolkits/index') }}">packages</a>
+    +    extend and build on Matplotlib functionality,
+    +    including a choice of two projection and mapping toolkits
+    +    <a href="http://matplotlib.org/basemap">basemap</a> and
+    +    <a href="http://scitools.org.uk/cartopy/docs/latest">cartopy</a>

+    +.. warning::
+    +   *axisartist* uses a custom Axes class
+    +   (derived from the mpl's original Axes class).
+    +   As a side effect, some commands (mostly tick-related) do not work.
+    +
+    +
+    +The *axisartist* contains custom Axes class that is meant to support for
+    +curvilinear grids (e.g., the world coordinate system in astronomy).
+    +Unlike mpl's original Axes class which uses Axes.xaxis and Axes.yaxis
+    +to draw ticks, ticklines and etc., Axes in axisartist uses special
+    +artist (AxisArtist) which can handle tick, ticklines and etc. for
+    +curved coordinate systems.
+    +
+    +.. plot:: mpl_toolkits/axisartist/examples/demo_floating_axis.py
+    +
+    +Since it uses a special artists, some mpl commands that work on

+    +Unlike mpl's original Axes class which uses Axes.xaxis and Axes.yaxis
+    +to draw ticks, ticklines and etc., Axes in axisartist uses special
+    +artist (AxisArtist) which can handle tick, ticklines and etc. for
+    +curved coordinate systems.
+    +
+    +.. plot:: mpl_toolkits/axisartist/examples/demo_floating_axis.py
+    +
+    +Since it uses a special artists, some mpl commands that work on
+    +Axes.xaxis and Axes.yaxis may not work.
+    +
+    +axisartist
+    +----------
+    +
+    +*axisartist* module provides a custom (and very experimental) Axes
+    +class, where each axis (left, right, top and bottom) have a separate
+    +artist associated which is responsible to draw axis-line, ticks,

+    +
+    +Since it uses a special artists, some mpl commands that work on
+    +Axes.xaxis and Axes.yaxis may not work.
+    +
+    +axisartist
+    +----------
+    +
+    +*axisartist* module provides a custom (and very experimental) Axes
+    +class, where each axis (left, right, top and bottom) have a separate
+    +artist associated which is responsible to draw axis-line, ticks,
+    +ticklabels, label.  Also, you can create your own axis, which can pass
+    +through a fixed position in the axes coordinate, or a fixed position
+    +in the data coordinate (i.e., the axis floats around when viewlimit
+    +changes).
+    +
+    +The axes class, by default, have its xaxis and yaxis invisible, and

+    +Since it uses a special artists, some mpl commands that work on
+    +Axes.xaxis and Axes.yaxis may not work.
+    +
+    +axisartist
+    +----------
+    +
+    +*axisartist* module provides a custom (and very experimental) Axes
+    +class, where each axis (left, right, top and bottom) have a separate
+    +artist associated which is responsible to draw axis-line, ticks,
+    +ticklabels, label.  Also, you can create your own axis, which can pass
+    +through a fixed position in the axes coordinate, or a fixed position
+    +in the data coordinate (i.e., the axis floats around when viewlimit
+    +changes).
+    +
+    +The axes class, by default, have its xaxis and yaxis invisible, and
+    +has 4 additional artists which are responsible to draw axis in

matplotlib/matplotlib

Join GitHub today

Reorganise mpl_toolkits documentation #5752

Conversation

jenshnielsen commented Dec 26, 2015

tacaswell added the needs_review label Dec 26, 2015

tacaswell commented Dec 28, 2015

jenshnielsen commented Dec 28, 2015

tacaswell commented Dec 28, 2015

jenshnielsen commented Dec 28, 2015

jenshnielsen referenced this pull request Dec 29, 2015

jenshnielsen changed the title from [WIP] Reorganise mpl_toolkits documentation to Reorganise mpl_toolkits documentation Dec 29, 2015

jenshnielsen commented Dec 29, 2015

WeatherGod commented Dec 29, 2015

jenshnielsen commented Dec 29, 2015

WeatherGod commented Dec 29, 2015

jenshnielsen commented Dec 29, 2015

WeatherGod commented Dec 29, 2015

WeatherGod commented Dec 29, 2015

jenshnielsen commented Dec 29, 2015

jenshnielsen commented Dec 29, 2015

Show 2 comments Hide comments mdboom commented on an outdated diff Dec 29, 2015

Show 1 comment Hide comment mdboom commented on an outdated diff Dec 29, 2015

Show 1 comment Hide comment mdboom commented on an outdated diff Dec 29, 2015

Show 1 comment Hide comment mdboom commented on an outdated diff Dec 29, 2015

Show 1 comment Hide comment mdboom commented on an outdated diff Dec 29, 2015

mdboom commented Dec 29, 2015

jenshnielsen commented Dec 29, 2015

mdboom commented Dec 29, 2015

jenshnielsen commented Dec 29, 2015

mdboom commented Dec 29, 2015

mdboom commented Dec 29, 2015

jenshnielsen commented Dec 30, 2015

jenshnielsen commented Dec 30, 2015

WeatherGod commented Dec 30, 2015

jenshnielsen commented Dec 30, 2015

WeatherGod commented Dec 30, 2015

jenshnielsen referenced this pull request Jan 2, 2016

jenshnielsen commented Jan 4, 2016

jenshnielsen added some commits Dec 26, 2015

All checks have passed

jenshnielsen commented Jan 5, 2016

jenshnielsen commented Jan 5, 2016

Show 1 comment Hide comment WeatherGod commented on an outdated diff Jan 5, 2016

jenshnielsen commented Jan 5, 2016

Show 2 comments Hide comments WeatherGod and 1 other commented on an outdated diff Jan 5, 2016

Show 1 comment Hide comment WeatherGod commented on an outdated diff Jan 5, 2016

WeatherGod commented Jan 5, 2016

All checks have passed

WeatherGod commented Jan 5, 2016

jenshnielsen commented Jan 8, 2016

WeatherGod added a commit that referenced this pull request Jan 8, 2016

Hide details View details WeatherGod merged commit 5eec831 into matplotlib:master Jan 8, 2016 3 checks passed

3 checks passed

tacaswell removed the needs_review label Jan 8, 2016

WeatherGod commented Jan 8, 2016

jenshnielsen deleted the jenshnielsen:axisgriddocs branch Jan 8, 2016

QuLogic modified the milestone: next major release (2.0), proposed next point release (2.1) Jan 8, 2016

QuLogic added a commit to QuLogic/matplotlib that referenced this pull request Oct 19, 2016

QuLogic added a commit to QuLogic/matplotlib that referenced this pull request Oct 19, 2016

This was referenced Oct 19, 2016

mdboom commented on an outdated diff Dec 29, 2015

mdboom commented on an outdated diff Dec 29, 2015

mdboom commented on an outdated diff Dec 29, 2015

mdboom commented on an outdated diff Dec 29, 2015

mdboom commented on an outdated diff Dec 29, 2015

WeatherGod commented on an outdated diff Jan 5, 2016

WeatherGod and 1 other commented on an outdated diff Jan 5, 2016

WeatherGod commented on an outdated diff Jan 5, 2016

WeatherGod merged commit `5eec831` into matplotlib:master Jan 8, 2016
3 checks passed