DOC: simplify API index #19727
DOC: simplify API index #19727
Conversation
2716870 to
0e26ab8
Compare
|
We had API in the top menu until https://matplotlib.org/3.1.0/. I think it was removed intentionally, but don't remember the discussion. |
|
Yes, it was removed here: https://github.com/matplotlib/matplotlib/pull/15489/files I don't see much discussion of dropping API... |
doc/api/index.rst
Outdated
| (Note that there is also a parallel `matplotlib.pyplot` API interface | ||
| that is considered useful for interactive work; see | ||
| :ref:`usage patterns <usage_patterns>`, below). |
There was a problem hiding this comment.
| (Note that there is also a parallel `matplotlib.pyplot` API interface | |
| that is considered useful for interactive work; see | |
| :ref:`usage patterns <usage_patterns>`, below). | |
| Alternatively, there is also a parallel `matplotlib.pyplot` API interface | |
| that is considered useful for interactive work; see | |
| :ref:`usage patterns <usage_patterns>`, below. |
There was a problem hiding this comment.
But I'm not sure we should mention the distinction here at all. Particularly also because the following example uses the object-based approach, but still needs to use pyplot for Figure and Axes creation. It's quite confusing that the non-pyplot approach still needs pyplot. So, I'd not go into the details here.
There was a problem hiding this comment.
Sure - I struggled a bit with how to work this in, or if I should. It is such a common point of confusion that someone wrote a whole section and stuck it at the top of the API docs, so it seemed at least referring to it near the top would be useful, but I'm happy to leave it out.
|
|
||
| The pylab API (disapproved) | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True) |
There was a problem hiding this comment.
| fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True) | |
| fig, ax = plt.subplots() |
Keep it simple without parameters. While constrained_layout is nice, IMHO this is not the place to teach it (and the benefit for this simple plot is small).
There was a problem hiding this comment.
Yes, but then the figure is too large, in my opinion.
There was a problem hiding this comment.
You could try with
.. plot::
:scale: 50 %
but I'm not sure if that will look good.
There was a problem hiding this comment.
Yeah, I wish there was a two-column view.... We could just include the code and the figure as an image as well. I do think the example is useful, though, to make it concrete what we are talking about.
There was a problem hiding this comment.
By default, the ylabel is cutoff, so some formatting is necessary anyway.. Might as well keep what is above. I don't think we need to explain every incantation everywhere it appears.
Co-authored-by: Tim Hoffmann <[email protected]>
doc/api/index.rst
Outdated
| ax.plot(x, y) | ||
| ax.set_xlabel('t [s]') | ||
| ax.set_ylabel('S [V]') | ||
| fig.suptitle('Sine wave') |
There was a problem hiding this comment.
| fig.suptitle('Sine wave') | |
| ax.set_title('Sine wave') | |
| fig.patch.set_color('lightsteelblue') |
One would not use fig.suptitle with a single Axes. This looks a bit odd because the title is centered on the figure not the Axes. There are actually not too many reasonable uses for figure methods in this simple example. Coloring the background may be one of the better ones.
There was a problem hiding this comment.
Are we trying to soft deprecate fig.set_facecolor? I understand not wanting duplicate ways of doing the same thing, but asking folks to modify a property like this is a discoverability issue.
|
|
||
| Modules | ||
| ------- | ||
|
|
||
| Matplotlib consists of the following submodules: | ||
| Alphabetical list of submodules: | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 1 |
There was a problem hiding this comment.
| :maxdepth: 1 | |
| :maxdepth: 1 | |
| :multicol-toc: |
Maybe.
There was a problem hiding this comment.
Is this unreleased? I get /Users/jklymak/matplotlib/doc/api/index.rst:45: WARNING: Error in "toctree" directive: unknown option: "multicol-toc". on sphinx 3.5.3
There was a problem hiding this comment.
Sorry, this should have been :class: multicol-toc.
multicol-toc is just a CSS class we have added to our mpl.css.
There was a problem hiding this comment.
oops searched the internet - didn't think to search our source code...
There was a problem hiding this comment.
Sorry this does not seem to work. .. toctree: does not support a :class: attribute.
I've otherwise only used it for .. contents: so far. The above screenshot was a hacked CSS in the browser, because I didn't want to wait for a docs build.
Seems we have to live with the long list for now.
There was a problem hiding this comment.
Ha! I thought I was going crazy... Certainly adding a class directive to toctree seems like a good idea, but seems like an upstream issue.
308bc7b to
71fa500
Compare
|
I'm good with this as it is now, but did not catch up on the full discussion so am holding off on merging. |
|
Thanks both! |
PR Summary
This yields a much quicker ingress to the useful parts of the API page, and a quick example to orient the reader...
PR Checklist
pytestpasses).flake8on changed files to check).flake8-docstringsand runflake8 --docstring-convention=all).doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).