Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: Adding example references for API & Pyplots sections #11353

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.

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

Conversation

ImportanceOfBeingErnest
Copy link
Member

@ImportanceOfBeingErnest ImportanceOfBeingErnest commented May 31, 2018

PR Summary

This is part of creating backreferences for the examples.
as discussed in #11019 and #10148 and #10974.

This PR concerns the

  • API
  • Pyplots

sections of the gallery.

In addition,

  • examples explaining how to create parasite axes are linked in between them to reduce confusion from the 3 different ways to achieve the same goal.
  • The examples/pyplots/compound_path_demo.py is removed and the non-overlapping content added to the examples/api/histogram_path.py histogram example.

Copy link
Member

@jklymak jklymak left a comment

Choose a reason for hiding this comment

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

This looks great, but see comments below for a few questions. Thanks!

@@ -1,51 +0,0 @@
"""
Copy link
Member

@jklymak jklymak May 31, 2018

Choose a reason for hiding this comment

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

Did you mean to delete this demo? If you meant to, then whats the rationale? EDIT: oops, sorry I see it above...

# The use of the following functions, methods, classes and modules is shown
# in this example:

import matplotlib
Copy link
Member

Choose a reason for hiding this comment

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

So I guess I'm not sure if we should have every fcn used by every example listed like this... Are you curating this at all?

Copy link
Member Author

Choose a reason for hiding this comment

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

I'm curating this a bit indeed. But I may have been inconsistent in doing so in some places.
In general I'm aiming at putting those functions/methods classes in the references that are important for the example. E.g. if the example treats some complex histogram plotting, I won't put ax.set_xlabel in the references. If the example aim is to to show some basic plotting, I'm putting the basic functions in. So far I've also tried to make sure there is at least one example for each new method I came accross, so the whole process surely depends a bit on the order of processing the examples - which is admitedly arbitrary.
But there might be cases where I deviated from that strategy - it's always a bit handwavy.

In this particular case I guess the logic was that the example is rather basic and those methods had not been covered previously as far as I remember.

Copy link
Member Author

Choose a reason for hiding this comment

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

That being said, I guess it's beneficial to be slightly more inclusive with references for now. Later, once all examples have a reference section, the aim would be to inversely go through the docs and see if there are overcrowded gallery sections - in which case one can easily remove some references in those examples, as well as see if there are still methods or classes which do not have an example, but should - in which case one can either add a new example or find an existing one which can be modified.

At the end one benefit of those references will also be to manually check example coverage of the library.

"""
import matplotlib.pyplot as plt
plt.plot([1,2,3,4])
plt.ylabel('some numbers')
plt.show()

#############################################################################
Copy link
Member

Choose a reason for hiding this comment

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

At this point I'm wondering if there is not a way to automate this block of text that is cut and pasted between 52 files here. If we decide the change the heading from "References" to "Methods in this example" we will have to go through all these changes and edit by hand. I'm not familiar enough w/ Sphinx/gallery to know if there is a macro definition possible, but maybe we should check if there is?

Copy link
Member Author

Choose a reason for hiding this comment

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

As far as I can tell there is no way to manipulate the way sphinx-gallery processes the .py files - other than monkey-patching sphinx-gallery. I took this approach in #11169. However since here we need to change the content of this "Reference" section manually, such approach would be really complicated.

However, I think it should be relatively easy to change the section heading via search&replace (possibly with regex) in case that would be needed in the future.

Copy link
Contributor

Choose a reason for hiding this comment

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

For the record I have a work in the plans to make this kind of referencing completely automated (using a rewrite from scratch of s-g, as there are a bunch of things I don't like in their design anyways).
(The idea being to inject an AST transformer to transform foo.bar to logged_getattr(foo, "bar") at the AST level, so that I know what is the actual name that needs to be linked at what point in the source.)

Copy link
Member Author

Choose a reason for hiding this comment

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

@anntzer On what timescale do you plan to do this? In how far should this prevent us from continuing adding the backreferences manually?

Copy link
Contributor

Choose a reason for hiding this comment

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

I "should" have something by the end of the month.

@ImportanceOfBeingErnest
Copy link
Member Author

I just saw that this would conflict with #11136, where @dstansby removes the /api section of the gallery and distributes the examples to other sections. Not sure which one should be merged first, such that rebasing is kept easy for the other one.

@jklymak
Copy link
Member

jklymak commented Jun 1, 2018

See discussion on gitter. @anntzer points to this rebase strategy. https://stackoverflow.com/questions/42568138/git-rebase-with-renamed-files

Given that #11136 is not passing tests, I think we can postphone the rebase pain to that PR based on the article above...

@dstansby
Copy link
Member

dstansby commented Jun 1, 2018

Sorry, I don't have time for #11136 and will be away next week, happy to take on the rebase pain when I'm back!

@jklymak
Copy link
Member

jklymak commented Jun 1, 2018

OK, thanks @dstansby I think they are both worthwhile PRs, and am happy to help w/ the rebase if it gets hairy...

@jklymak jklymak added this to the v2.2-doc milestone Jun 1, 2018
@jklymak jklymak merged commit f0e3fe7 into matplotlib:master Jun 1, 2018
lumberbot-app bot pushed a commit that referenced this pull request Jun 1, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants