DOC: Nav-bar: Add icon linking to contents #21224
Conversation
Build wheels for Apple Silicon.
Mostly D401 (imperative mood) fixes, and a few other things.
When referring to a font glyph, "glyph name" is standard terminology (e.g. FT_Get_Glyph_Name or Adobe docs); additionally there is a separate concept of "symbol_name" used by the mathtext parser which has a different meaning (`\foo` commands referring to TeX symbol names), so let's not confuse them. symbol_name is kept in the mathtext SimpleNamespaces for backcompat (changing the SimpleNamespace to a proper class with a property handling the deprecation is not worth the work).
Docstring cleanups.
Clarify support for 2D coordinate inputs to streamplot.
Cleanup some dviread docstrings.
…tion DOC Use 'Axes' instead of 'axes' in axes._base.py
Rename symbol_name to glyph_name where appropriate.
The constructores are entirely identical (including wrt. defaults and docstrings).
Make HandlerLine2D{,Compound} inherit constructors from HandlerNpoints.
On Gtk4, these have never been part of a released version, and can be directly removed.
It is nicer to just define them at the point of use rather than ~400 lines later.
Try running e.g. examples/widgets/textbox.py together with `rcParams["toolbar"] = "toolmanager"`. Before this fix, clicking on the TextBox would result in "TypeError: push() takes 2 positional arguments but 3 were given".
Fix ToolManager + TextBox support.
These entries have already been removed (with the corresponding API change documentation). Also remove the now-unused _all_deprecated.
The docs should present mpl_toolkits as more or less regular modules,
that just happen to live in a different toplevel package for historical
reasons. So just concatenate them to the end of the main module list.
(This is particularly in preparation of the new website redesign, where
the separate "Extra Toolkits" grouping is really too conspicuous on the
front page.)
Remove the toolkits/index page (documenting mplot3d and
axis_grid/axisartist ("ag/aa") together doesn't make much sense except
for this historical grouping), merging the mplot3d intro blurb together
with the one previously at mplot3d/index.rst; the ag/aa blurbs were
just included from the ag/aa API docs themselves and therefore don't
need to be kept.
The mplot3d intro blurb itself can go to the top of the mplot3d API
docs, rather than needing a separate page.
Deemphasize mpl_toolkits in API docs.
Remove now-unused rcParams _deprecated entries.
DOC: Compress comments in make_image.
DOC: Use correct confidence interval in example prose
Parametrize/simplify test_missing_psfont.
dd73697 to
3fd78f1
Compare
|
Hmm, that's not normally how I expect a hamburger icon to work. |
|
Happy to User other icons such as
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 to https://matplotlib.org/devdocs/index.html#, which is what I'd expect. That page should be the table of contents, and I'm not sure why we would have another? |
TL;DRIndex 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. ExplanationIndex pagePurpose:
Advantage: We have more space for information than only a navbar link. Table of contentsPurpose: Structured overview of all the contents on the page. Nav barAdvantage: Available on every page. 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:
|
|
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. |
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 articles https://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 to |
|
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 have I'm suggesting the simple solution is to put most of the info that is not example galleries, API reference, or Contributing under Navbar:
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: |
|
Here is an attempt to implement what I'm suggesting: #21251 |
|
BTW, I'm open to inverting #21251 and moving all the references to |
|
On hold during #21251 discussion. |
|
Superseeded by #21251 |
PR Summary
The contents page should be easily accessible from every page, which means it should be linked in the nav bar.
OTOH the current nav bar is not a complete site navigation but rather a collection of selected important topics. Putting a textual "Contents" link feels a bit out of place. Therefore, I've chosen the icon link.
Since we have the nav link, we can also remove the Site map section from the index page. That section was only added to have a link to the contents page somewhere.
The HTML is not very elegant. Explicit style and the nbsp are necessary to get position and size correct relative to the text nav links. Possibly somebody with more HTML/CSS knowledge could do this better, but it works.
before:
after:
possible alternative icon
