"inner" index reorganization #20867

tacaswell · 2021-08-20T17:59:28Z

The top bar is too crowded so this moves the Third-party and contributing links out of the top bar and moves them to the version-specific landing page.

story645 · 2021-08-20T21:00:10Z

Agree it's too cluttered, but what about moving reference to the version specific pages since it only makes sense in context of a specific version?
Maybe third-party-package should be renamed ecosystem since that's what everyone else is calling their analogous pages?

timhoffm · 2021-08-20T23:35:47Z

Agreed that it's too crowded. However, I'm neither happy with the current nor with the proposed structure. I'd need a moment to sit down and work out what's really the issue and propose something better. In the context of the upcoming 3.5 release: When do we need this to be finished? Are there plans to still work on the index page?

tacaswell · 2021-08-21T19:42:13Z

I think we have 2-3 weeks to get the inner index (as produced by sphinx) and the brochure site (@dorafc is looking at it right now) ready.

Doing a quick survey, the headings across the top for :

numpy: ['User Guide', 'API reference', 'Development'] https://numpy.org/doc/stable/index.html

pandas: ['Getting Started', 'User Guide', 'API reference', 'Development', 'Release notes'] https://pandas.pydata.org/docs/getting_started/index.html

scipy: ['Getting started', 'User Guide', 'API refernec', 'Development', 'Release notes'] http://scipy.github.io/devdocs/index.html

networkx: ['Install', 'Tutorial', 'Reference', 'Developer', 'Gallery', 'Guides->'] https://networkx.org/documentation/stable/index.html

Bokeh: [, 'First steps', 'User Guide', 'Gallary', 'Reference', 'Developers', 'Releases', 'Tutorial->', 'Community->'] https://docs.bokeh.org/en/latest/index.html

binder: ['Tutorials', 'How-to Guides', 'Reference', 'About mybinder.org', 'Contribute'] https://mybinder.readthedocs.io/en/latest/

For one thing the consensus seems to be to spell it "User Guide" not "User's Guide". I have not chased down what is in each of those

I'm going to push a bunch more re-organization work to this branch (some of it conceptual, some of it trying to get the navigation to play nice).

I think putting the release notes an their own top-level thing makes a lot of sense. My current plan is:

pull "installation" out of the top-bar
put the pip install matplotlib and conda install matplotlib options as the first section of the inner index page
move the detailed installation to the "User Guide"
put the release notes in the top bar
put the learn / reference / how-to / understand into the actual grid.
move the "back matter" (citing, license, history, credit) to be at the bottom of the inner index page

The user profiles I'm thinking about are and what they want from the site in order to make progress on what ever it is they are actually doing that they need to use Matplotlib on the path to.

new-to-Matplotlib users (who have already decided / been told they are going to use Matplotlib). They need to find the installation instructions (including links to when the happy-path does not work), the "plot types", the tutorials, the gallery, and where to interact with a human if they want to (probably in that order). While installation is important, it is a one(few)-time thing (and we have the same process as everyone else on the standard platforms at this point) so I do not think we need to spend the real-estate on every single inner page on a direct link to installation, prominent placement on the inner index page is enough.
current Matplotlib users. This is people who have read some examples on line or gone through a boot camp. They have used Matplotlib to get their work done in the past, they have come back to us with a specific goal of the visualization they want to make. They are probably just making visualizations for themselves (or to present only the output to others) and most of the code they write using Matplotlib is going to be one-offs in a terminal or in a jupyter notebook. The Plot Types sub-gallery is not as useful to them (they know we can do bar charts, but now they want to do stacked bars with labels and error bars on them). We need to direct these users to the gallery, the API reference, the tutorials, and then channels to talk to a human.
Matplotlib "power users". This is people who are extensive users of Matplotlib and have written significant amounts of code that depends on Matplotlib that is in turn used by other people or users who are trying to push the boundaries of what you can do with Matplotlib. They probably want access to the API reference, the gallery, the user guide, the release notes, the tutorials, and then channels to talk to a human.

story645 · 2021-08-22T01:51:53Z

However, I'm neither happy with the current nor with the proposed structure. I'd need a moment to sit down and work out what's really the issue and propose something better

I think we all agree it's trying to do too many things, and it seems like Tom's proposal is slim it down to just folks who need to read the docs (judging by the user stories), and let the new "matplotlib.org" handle the community roadmapping (ecosystem & contributing).

Plot Types and Gallery are also overlapping in weird ways, but I dunno that a gallery landing page/drop down is the right solution/too much.

I'm unsure about user guide as a top level link 'cause currently it isn't and instead acts as a half filled index. I think Tom is trying to address some of this by moving installation there, and reworking how the things in the guide are linked, but the current contents of the guide are basically all things that folks have proposed should be moved:

interactive figures & fonts - Convert remaining narrative docs to tutorials #19688 move to tutorial
release notes - this should have it's own page and TOC, not be enumerated in the guide like this
license/citation/credits/history - move links to TOC & lives in brochure site
external resources - External learning resources mpl-third-party#71
FAQ - Deprecate FAQ & integrate content into other parts of docs #17920

doc/index.rst

doc/users/resource.rst

timhoffm · 2021-08-22T22:19:32Z

doc/users/release_notes.rst

-.. include from another document so that it's easy to exclude this for releases
-.. include:: release_notes_next.rst
-
-3.4


What is the benefit of splitting this page? AFAICS there is no difference in the rendering other than we have additional but pretty useless toc pages per version (https://63048-1385122-gh.circle-artifacts.com/0/doc/build/html/users/relnotes/3.4.html).

From a maintainance POV I think having everything in one file is simpler because one can more easily see what is there.

Before doing this re-org the list on the left has nice accordion things

instead of being one long list on my local build. I'm using the latest pydata-sphinx-theme which apparently renders differently....

timhoffm

Generally, this is on a good way. I particularly like the landing page.

I still struggle with the toc structure. The landing page is great for topical redirection, but we don't have a toc anywhere that shows everything. E.g. Contributing is only linked at the bottom of the landing page.

Since we cannot use the top bar as top-level navigation, we need a separate page that structures everything and contains the full TOC. For now, I call this "Site map", but there may be a better name (maybe just "Matplotlib 3.5 documentation"?). Structure could be:

Site map
- Installation
- User documentation
  - Explanations
    [ can gallery and tutorials be linked in here? ]
  - API reference
  - FAQ
- External resources
- Release notes
- Back matter
  - License
  - Citing
  - Credits
  - History
- Contributing

The landing page (index.rst) should not define the structure. It's not meant as a full overview and thus cannot be the top-level defining element. It rather announces the most relevant parts of the docs and links there.

doc/index.rst

story645

I still don't like that the user guide is functioning more as a site map than a guide - who is the intended audience for the user guide?

doc/index.rst

story645 · 2021-08-23T02:51:02Z

doc/index.rst

+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    - The :ref:`users-guide-explain` section of the :doc:`Users guide <users/index>`
+    - Many of the :doc:`Tutorials <tutorials/index>` have explanatory material


I think a show not tell approach could work better here, something like

Suggested change

- Many of the :doc:`Tutorials <tutorials/index>` have explanatory material

- :doc:`Tutorials <tutorials/index>` on topics such as usage, customization, color, fonts, etc.

doc/index.rst

doc/users/backmatter.rst

timhoffm · 2021-08-23T07:52:16Z

I still don't like that the user guide is functioning more as a site map than a guide - who is the intended audience for the user guide?

That is addressed in my comment #20867 (review). The user guide is gone there. I don't think we need a section "user guide" at all.

tacaswell · 2021-08-24T03:19:50Z

I still struggle with the toc structure.

It is made worse because the .. toc:: structure is also used by sphinx to decide things like the "next" buttons, the auto-tocs on the left and right, and the the bread-crumbs in the top-bar (for example if you put anything else from the top-bar in the user in another one, they both show bold when you are in the inner one which I found very confusing).

https://63048-1385122-gh.circle-artifacts.com/0/doc/build/html/contents.html does existing but we do not link to it anyplace obvious. I guessed that it existed, because a contents.rst exists and suppressing sphinx from making a page while also using it to populate the top bar seemed hard! From there you can search for it and we do link to it a few random places (like the prose at the top of gallery).

I think the toc rules should be that contents.rst is the root of all files that have tocs and you can only use .. toc:: in files that are in a toc in a file that is already referenced.

My concern with your proposed layout @timhoffm is that we lose a way to pull apart the 4 kinds of docs that https://documentation.divio.com/structure/ defines.

I suspect that there is going to have to be some negoitation between pydata-sphinx-theme and sphinx-gallery to tweak how they generate TOCs to fold some things nicer.

tacaswell · 2021-08-24T03:30:22Z

This is where I uncritically adopted the install card from: http://scipy.github.io/devdocs/getting_started.html#getting-started-ref

timhoffm · 2021-08-24T08:36:11Z

I still struggle with the toc structure.

It is made worse because the .. toc:: structure is also used by sphinx to decide things like the "next" buttons, the auto-tocs on the left and right, and the the bread-crumbs in the top-bar (for example if you put anything else from the top-bar in the user in another one, they both show bold when you are in the inner one which I found very confusing).

We should hide the prev/next buttons. They only make sense in a linear book-style doc, not in a hierarchial structure where each page stands for a dedicated topic.
Here is how to: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#hiding-the-previous-and-next-buttons

Auto-tocs should be more or less ok for us.

Top-bar is an issue. Can we work around that using external links? https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#adding-external-links-to-your-nav-bar

I think the toc rules should be that contents.rst is the root of all files that have tocs and you can only use .. toc:: in files that are in a toc in a file that is already referenced.

Yes.

My concern with your proposed layout @timhoffm is that we lose a way to pull apart the 4 kinds of docs that https://documentation.divio.com/structure/ defines.

I can't follow. The 4 kinds of docs should become elements in the "User documentation" section once we get to properly distinguish between them.

jklymak · 2021-08-24T15:34:34Z

Taking a quick look, I don't think its impossible to move "Plot Types" into "Gallery", and just putting them at the top. Not sure how nestable S-G is.

OTOH, I think I agree that "Contributing" does not need a top-level link in the banner. I think folks who want to contribute can find that either on the landing page or the "Users Guide" or via google, 99.9% of users probably don't "Contribute", and those that do, probably only need the Contribute guide until they get their feet under them.

Thanks, this is looking good!

tacaswell · 2021-08-24T17:23:25Z

I can't follow. The 4 kinds of docs should become elements in the "User documentation" section once we get to properly distinguish between them.

Sorry, I think I miss-understood your outline with the gallery and tutorials being under "Explanation" rather than as peers to it.

We should hide the prev/next buttons.

done

I don't think its impossible to move "Plot Types" into "Gallery", and just putting them at the top

For the "New to Matplotlib" user above I think it is worth having the very streamlined "this is the kind of thing you can do" entry point always easy to get to.

Top-bar is an issue. Can we work around that using external links?

The external links in the conf adds links with the -> icon next to it:

however, I stand by not keeping the link to third-party in the top line

I'll play around later with trying to use (internal) links in the top bar and seeing what that does, but my suspicion is that it is going to break the bread-crumb behavior.

jklymak · 2021-08-24T18:52:23Z

Agree about third party as a top bar issue. Users don't need to frequently access that and I assume it is on both the landing page and somewhere in the user guide.

QuLogic · 2021-08-26T20:23:18Z

Cards without bullet markers:

QuLogic · 2021-08-26T20:29:14Z

Maybe with a bit of spacing to make it clearer these are separate

tacaswell · 2021-09-04T00:10:56Z

ok, I think I got the top bar and over all structure to be what @timhoffm proposed last week!

timhoffm · 2021-09-04T23:39:47Z

Thanks Tom, this looks great!

Still two things:

The top bar "Release notes" link is broken.
Coming back again to the Release notes toc splitting into several files ("inner" index reorganization #20867 (comment))
I don't follow the most recent changes in the sphinx-pydata-theme but at least in CI this renders as
https://63285-1385122-gh.circle-artifacts.com/0/doc/build/html/users/release_notes.html and
https://63285-1385122-gh.circle-artifacts.com/0/doc/build/html/users/relnotes/3.4.html
which needs annoyingly many clicks to get somewhere.
I'd like to have this type of page back https://matplotlib.org/devdocs/users/release_notes.html.

anntzer · 2021-09-05T09:51:47Z

doc/index.rst

+        pip install matplotlib
+
+
+Further details are availabe in the :doc:`Installation Guide <users/installing>`.


typo: available

tacaswell · 2021-09-09T19:00:24Z

The top bar "Release notes" link is broken.

I had a commit that fixed that that I had failed to push 🤦🏻

Coming back again to the Release notes toc splitting into several files

dropped that commit (and opened #21027 ) to talk about that later.

timhoffm · 2021-09-09T19:35:01Z

Doc build failure:

/home/circleci/project/doc/index.rst:90: WARNING: unknown document: api/toolkits/index

Edit: Ah, that's because of #21003.

doc/index.rst

tacaswell · 2021-09-10T02:27:31Z

I really do not like they way this renders the left nav on the release notes:

(this is what I get locally)

timhoffm

I agree that the left nav for the "Release notes" is awkward. Probably, because all next-lower level sections are on the page itself and I assume that the on-page sections go on the right nav whereas links to other pages go to the left nav.

Anyway, I propose to merge nonetheless. It would even be bearable to use this state for release. While the left nav is pretty useless as is, I assume that people will be visually drawn to the large "Version x.y" headings on the page and mostly ignore the noise on the left bar. Also we have #21027 to address this further.

jklymak

A bunch of minor comments that you can take or leave and/or could be addressed after merging

I guess this should be squashed as well, but I think anyone can merge if squashed....

jklymak · 2021-09-10T07:06:04Z

doc/conf.py

@@ -291,6 +294,12 @@ def _check_dependencies():
 html_theme_options = {
    "logo_link": "index",
    "collapse_navigation": True if CIRCLECI else False,
+    # "external_links": [


Did you want to keep this comment?

It should go as I think it is extra-useless as this is read by navbar_center template that got replaced a bit further down.

doc/index.rst

jklymak · 2021-09-10T07:12:26Z

doc/index.rst

+    - :doc:`Axes API <api/axes_api>` for *most* plotting methods
+    - :doc:`Figure API <api/figure_api>` for figure-level methods
+    - Top-level interfaces to create:
+
+      - Figures (`.pyplot.figure`)
+      - Subplots (`.pyplot.subplots`, `.pyplot.subplot_mosaic`)


Maybe this should be a sublist because these are all under api/index. But not sure how it renders...

Suggested change

- :doc:`Axes API <api/axes_api>` for *most* plotting methods

- :doc:`Figure API <api/figure_api>` for figure-level methods

- Top-level interfaces to create:

- Figures (`.pyplot.figure`)

- Subplots (`.pyplot.subplots`, `.pyplot.subplot_mosaic`)

- :doc:`Axes API <api/axes_api>` for *most* plotting methods

- :doc:`Figure API <api/figure_api>` for figure-level methods

- Top-level interfaces to create:

- Figures (`.pyplot.figure`)

- Subplots (`.pyplot.subplots`, `.pyplot.subplot_mosaic`)

I'm going to hold off on this one as if everything but one is in the second sub-list we should find some other way to structure this.

doc/faq/index.rst

tacaswell · 2021-09-11T21:03:29Z

I squashed it down to three commits (one for the sponsor button, one for the version bump, one for everything else).

This does several things to the documentation: - Restructures the top-level TOC (as given by contents.rst) to be flatter and highlight were the 4 kinds of documentation are in the docs. - Changes the "inner" index page to better serve existing Matplotlib users by making it easier to find the kind of documentation they need. - Replaces the default top-level nav bar with a custom template that is not directly taken from the TOC layout given in contents.rst. We want to highlight (and provide easy access to) different things than the top-level structure of the overall docs. The current contents (and the links) of the navbar are hard-coded in doc/_templates/mpl_nav_bar.html - Adds the search bar back to the left nav on the inner index Co-authored-by: Jody Klymak <jklymak@gmail.com> Co-authored-by: hannah <story645@gmail.com> Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

timhoffm · 2021-09-12T07:12:37Z

Let‘s go. 🎉 Further refinements can be done in follow-up PRs.

…867-on-v3.5.x Backport PR #20867 on branch v3.5.x ("inner" index reorganization)

Remove generated file accidentally added in #20867

…d in matplotlib#20867

…067-on-v3.5.x Backport PR #21067 on branch v3.5.x (Remove generated file accidentally added in #20867)

"inner" index reorganization

Remove generated file accidentally added in #20867

tacaswell added this to the v3.5.0 milestone Aug 20, 2021

story645 added Documentation Documentation: website layout/behavior/styling changes labels Aug 20, 2021

tacaswell force-pushed the doc_index_reorg branch from 4e814a3 to 9cd0a35 Compare August 20, 2021 19:34

tacaswell force-pushed the doc_index_reorg branch from 9cd0a35 to a8216e9 Compare August 22, 2021 01:07

timhoffm reviewed Aug 22, 2021

View reviewed changes

doc/index.rst Outdated Show resolved Hide resolved

story645 reviewed Aug 23, 2021

View reviewed changes

timhoffm mentioned this pull request Aug 23, 2021

Convert remaining narrative docs to tutorials #19688

Closed

tacaswell changed the title ~~Doc index reorg~~ "inner" index reorganization Aug 26, 2021

tacaswell force-pushed the doc_index_reorg branch 2 times, most recently from 2c13550 to f6fa78f Compare September 4, 2021 00:10

anntzer reviewed Sep 5, 2021

View reviewed changes

tacaswell force-pushed the doc_index_reorg branch from f6fa78f to 1083a35 Compare September 9, 2021 18:48

tacaswell mentioned this pull request Sep 9, 2021

Doc rearrange relnotes #21027

Draft

tacaswell force-pushed the doc_index_reorg branch from 1083a35 to daffe46 Compare September 9, 2021 18:51

timhoffm reviewed Sep 9, 2021

View reviewed changes

doc/index.rst Outdated Show resolved Hide resolved

timhoffm approved these changes Sep 10, 2021

View reviewed changes

jklymak approved these changes Sep 10, 2021

View reviewed changes

tacaswell added 2 commits September 11, 2021 16:51

DOC: add direct Matplotlib sponsorship to sponsor button

d78cdf6

DOC: push up sphinx-pydata-theme dependency

c69ed3f

tacaswell force-pushed the doc_index_reorg branch from fac72ef to 4c98316 Compare September 11, 2021 21:02

tacaswell force-pushed the doc_index_reorg branch from 4c98316 to 64df6ad Compare September 11, 2021 21:05

timhoffm merged commit 77aeddf into matplotlib:master Sep 12, 2021

meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Sep 12, 2021

Backport PR matplotlib#20867: "inner" index reorganization

a99befa

meeseeksmachine mentioned this pull request Sep 12, 2021

Backport PR #20867 on branch v3.5.x ("inner" index reorganization) #21052

Merged

dstansby added a commit that referenced this pull request Sep 12, 2021

Merge pull request #21052 from meeseeksmachine/auto-backport-of-pr-20…

eb35ad3

…867-on-v3.5.x Backport PR #20867 on branch v3.5.x ("inner" index reorganization)

tacaswell deleted the doc_index_reorg branch September 12, 2021 21:13

QuLogic added a commit to QuLogic/matplotlib that referenced this pull request Sep 13, 2021

Remove generated file accidentally added in matplotlib#20867

813f515

QuLogic added a commit to QuLogic/matplotlib that referenced this pull request Sep 13, 2021

Remove generated file accidentally added in matplotlib#20867

55b0d93

story645 added a commit that referenced this pull request Sep 13, 2021

Merge pull request #21067 from QuLogic/delete-extra

592319e

Remove generated file accidentally added in #20867

meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Sep 13, 2021

Backport PR matplotlib#21067: Remove generated file accidentally adde…

2c11e64

…d in matplotlib#20867

meeseeksmachine mentioned this pull request Sep 13, 2021

Backport PR #21067 on branch v3.5.x (Remove generated file accidentally added in #20867) #21068

Merged

QuLogic added a commit that referenced this pull request Sep 14, 2021

Merge pull request #21068 from meeseeksmachine/auto-backport-of-pr-21…

aef914d

…067-on-v3.5.x Backport PR #21067 on branch v3.5.x (Remove generated file accidentally added in #20867)

tacaswell pushed a commit that referenced this pull request Oct 20, 2021

Merge pull request #20867 from tacaswell/doc_index_reorg

04dc36b

"inner" index reorganization

tacaswell pushed a commit that referenced this pull request Oct 20, 2021

Remove generated file accidentally added in #20867

ab09bd4

tacaswell pushed a commit that referenced this pull request Oct 20, 2021

Merge pull request #21067 from QuLogic/delete-extra

6adaa70

Remove generated file accidentally added in #20867

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

"inner" index reorganization #20867

"inner" index reorganization #20867

tacaswell commented Aug 20, 2021

story645 commented Aug 20, 2021

timhoffm commented Aug 20, 2021

tacaswell commented Aug 21, 2021

story645 commented Aug 22, 2021 •

edited

Loading

timhoffm Aug 22, 2021

tacaswell Aug 24, 2021

timhoffm left a comment •

edited

Loading

story645 left a comment

story645 Aug 23, 2021

timhoffm commented Aug 23, 2021

tacaswell commented Aug 24, 2021

tacaswell commented Aug 24, 2021

timhoffm commented Aug 24, 2021

jklymak commented Aug 24, 2021

tacaswell commented Aug 24, 2021

jklymak commented Aug 24, 2021

QuLogic commented Aug 26, 2021

QuLogic commented Aug 26, 2021

tacaswell commented Sep 4, 2021

timhoffm commented Sep 4, 2021

anntzer Sep 5, 2021

tacaswell commented Sep 9, 2021

timhoffm commented Sep 9, 2021 •

edited

Loading

tacaswell commented Sep 10, 2021 •

edited

Loading

timhoffm left a comment

jklymak left a comment

jklymak Sep 10, 2021

tacaswell Sep 11, 2021

jklymak Sep 10, 2021

tacaswell Sep 11, 2021

tacaswell commented Sep 11, 2021

timhoffm commented Sep 12, 2021

	- Many of the :doc:`Tutorials <tutorials/index>` have explanatory material
	- :doc:`Tutorials <tutorials/index>` on topics such as usage, customization, color, fonts, etc.

		pip install matplotlib


		Further details are availabe in the :doc:`Installation Guide <users/installing>`.

"inner" index reorganization #20867

"inner" index reorganization #20867

Conversation

tacaswell commented Aug 20, 2021

story645 commented Aug 20, 2021

timhoffm commented Aug 20, 2021

tacaswell commented Aug 21, 2021

binder: ['Tutorials', 'How-to Guides', 'Reference', 'About mybinder.org', 'Contribute'] https://mybinder.readthedocs.io/en/latest/

story645 commented Aug 22, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm left a comment • edited Loading

Choose a reason for hiding this comment

story645 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm commented Aug 23, 2021

tacaswell commented Aug 24, 2021

tacaswell commented Aug 24, 2021

timhoffm commented Aug 24, 2021

jklymak commented Aug 24, 2021

tacaswell commented Aug 24, 2021

jklymak commented Aug 24, 2021

QuLogic commented Aug 26, 2021

QuLogic commented Aug 26, 2021

tacaswell commented Sep 4, 2021

timhoffm commented Sep 4, 2021

Choose a reason for hiding this comment

tacaswell commented Sep 9, 2021

timhoffm commented Sep 9, 2021 • edited Loading

tacaswell commented Sep 10, 2021 • edited Loading

timhoffm left a comment

Choose a reason for hiding this comment

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

Choose a reason for hiding this comment

tacaswell commented Sep 11, 2021

timhoffm commented Sep 12, 2021

story645 commented Aug 22, 2021 •

edited

Loading

timhoffm left a comment •

edited

Loading

timhoffm commented Sep 9, 2021 •

edited

Loading

tacaswell commented Sep 10, 2021 •

edited

Loading