Hmm, that's not normally how I expect a hamburger icon to work.

cc@tacaswell@dorafc

Happy to User other icons such as

• https://fontawesome.com/v5.15/icons/list?style=solid
• https://fontawesome.com/v5.15/icons/stream?style=solid
• https://fontawesome.com/v5.15/icons/th-list?style=solid

or anything else that conveys "table of contents".

So what happens now when I click on "Matplotlib"? Thats what I would expect to take me to the top of the docs, though maybe it now goes to the landing page?

Edit: currently it goes tohttps://matplotlib.org/devdocs/index.html#, which is what I'd expect. That pageshould be the table of contents, and I'm not sure why we would have another?

That page [index] should be the table of contents, and I'm not sure why we would have another?

TL;DR

Index and table of contents serve different purposes. Within our current doc structure, we need the freedom of having separate toc and index. We could try to rearrange things so that both fall together, but it would be a lot of work (which we are not able to do right now before 3.5) and I'm not convinced it's even possible.

Explanation

Index page

Purpose:

• Tell first-time visitors what matplotlib is in one sentence.
• Guide first-time visitors to relevant infos to get started (Installation, Quick Start guide)
• Highlight important parts of the docs for regular visitors (Learning resources)

Advantage: We have more space for information than only a navbar link.
Disadvantage: We shouldn't over-crowd this with less relevant content.

Table of contents

Purpose: Structured overview of all the contents on the page.
Advantage: We can show the full logical structure and all content.
Disadvantage: No priorization on important topics.

Nav bar

Advantage: Available on every page.
Disadvanage: Only few links possible
Purpose: Prominent links to most relevant and often used topics. (For example Installation is not in here, because you only need that once.)

Our page structure is slightly more complex due to that, but I think this makes sense:

Could we do it differently?

I claim we need an easily accessible table of contents so that one can see everything that is available on the page. I find the lack of a toc in the old page design quite frustrating because it's hard to find out what is available and how the whole docs is structured.

OTOH I don't think we should put all that content on the index page. Pages can get away with that if the nav bar reflects the top-level hierarchy of the toc. We don't want to do that because "Installation", "Project information" and "Search page" are reasonable top-level toc elements, but not important enough to be accessed from everywhere. OTOH, we want to highlight "Plot types", "Examples" and "Tutorials" which all logically belong into the usage guide. But we also want to link the usage guide itself.

Note also that we plan to move "Develop" out of the core documentation into a separate repo. Therefore it's nav entry will link to a page outside the toc.

So I think, we still need both:

• The contents page gives the overall site structure
• The nav and the index page specialize in guiding users to relevant information quickly.

I agree that the top-level nav should represent the doc structure as best we can.

I agree that "Installation" should be prominent on the index.html, but I don't think it logically requires it be at the top level of the docs: organizationally it could easily be a subdirectory under the usage guide. That applies even more so to "Project Information". If we move those two things down a level, then it makes the navbar largely correspond with the TOC, and have a few links that drill down a level for convenience.

I agree that the top-level nav should represent the doc structure as best we can.
I said, that this can be an aspirational goal for a project, but I also argued that "as best we can" is not good enough in our case and we thus need something else.

When I had a look at this as part of@tacaswell's restructing I didn't find a satisfying restructuring solution that'd allow to align nav bar and toc. You are welcome to propose a restructuring, but I think it has to be a complete proposal. Only saying "Installation can be part of the usage guide" is not enough. We have to make sure that every page has a logical place and the whole picture is consistent.

Have you considered putting the link to contents / site map in the footer?

I'd also suggest renaming "Site Map" to something like "table of contents" that more directly speaks to human users. The term sitemap generally refers to an SEO tool for bots to find content these days.

For what it's worth, you're dealing with a notably challenging information architecture problem here. This short book will be good intro to field -https://abookapart.com/products/everyday-information-architecture. Here are some more articleshttps://alistapart.com/blog/topic/information-architecture/

Thanks@dorafc! The "Site map" naming is a good point. Through this PR we get rid of that name.

Up to now, the footer is mainly a copyright notice. It would be awkward to only have the table of contents link in there. If we want to go this way, we'd need to have a broader thought on the footer.

I've switched the icon here tofa-list because that seems to be the common consensus when image-searching "table of contents icon". IMHO this is PR is an improvement of the current state. There might be some better solution, but that'd require significantly more work than I can do here. But if people think the icon is a bad idea, I'm ok to leave it.

I am in favor of pulling more stuff from the proposed footer from the brochure site and expanding the footer.

The problem right now is not too few table of contents - it is too many. We haveindex.html, we havecontents.html, and we haveusers/index.html which repeats most of contents.html, but not everything.

I'm suggesting the simple solution is to put most of the info that is not example galleries, API reference, or Contributing underusers/ and letusers/index.html serve as the table of contents for all the "rest" of the docs. I'd also propose movingfaq/ andresources/ to subdirectories ofusers/, but that is of secondary importance.

Navbar:

• Plot Types
  • as is
• Examples
  • as is
• Tutorials
  • as is
• API Reference (reference is too vague)
  • as is
• User's Guide
  • Installation
  • Examples and Tutorials (just relinks the navbar items)
    • Plot Types (don't list the next level down)
    • Tutorials ("")
    • Examples ("")
  • API Reference (no subheads, just relinks navbar)
  • Explanations and How-to
    • Troubleshooting
    • Usage patterns
    • Environmental variables
    • Fonts
    • Interactive Figures
    • Miscellaneous
  • External Resources
    • Books, chapters, and articles
    • Videos
    • Tutorials
  • Contributing (no subheads)
  • Project Information
    • License
    • Citing Matplotlib, Credits
    • History
  • Release Notes (no subheads)
• Contributing

I don't think this misses anything, and prevents us having the information in two places (and index.html).

EDIT: I think the release notes are important, but I'd link where we list the version info, not as a top navbar item.

So the solution is going the direction to put (almost) everything under "Usage guide". That's a conceptually viable approach, though I'm wondering if "Usage guide" is still the correct term then.

You started from Nav and put sections under that. Due to the technical realization in Sphinx, you have to go the other way round:
Nav is only a set of links we can point anywhere. There is however some constraint in the doc hierarchy of sphinx. Usually, you'll make a tree of the doc files by including them in the toc of the next higher level. This defines the global toc hierarchy. Our base file is currentlyhttps://github.com/matplotlib/matplotlib/blob/master/doc/contents.rst.
The main task is to reasonably setup that hierachy via.. toctree directives. By default, the toc is then also displayed on that page. That's certainly not what we want for index. You might be able to work around that with a:hidden: attribute and/or use.. ophan directives. Sorting out such a structure when you don't want to show it on index is a bit of a puzzle, but that's the way sphinx works.

Here is an attempt to implement what I'm suggesting:#21251

BTW, I'm open to inverting#21251 and moving all the references to/contents.html and getting rid of/users/index.html. We could probably just rename/users ->/miscellaneous which is what is in that directory now.

On hold during#21251 discussion.

Superseeded by#21251