moved doc root to landing page, make user landing a guide page #26332
Conversation
story645
added
Documentation: website
|
Reworked to be much more compact, mostly went w/ a two column structure where mostly orienting is on the left and TOC on the right, used cards for call outs and tried to keep headings for right hand side organization. The about us section looks a bit bare and that might be nice for an easter egg image - or alternatively I could put a side by side with the top line blurb , but I don't know that we want project info up top. Underneath are contribute and release notes which are also in the upper nav bar so I'm not super concerned about it being annoying to scroll to. For the most part tried to keep the flow in line w/ the navbar. ETA: If there's strong objection to plot types, I'll move that down to learn and use the rotator for the about double column .ETA 2: did this andI'll post as standalone commit once this one builds. Also learn can probably be changed to documentation since I think that's what most folks call that section. |
|
Plot types first: https://output.circle-artifacts.com/output/job/86fc3f41-39bb-4f15-91e0-2ccf58f04fa6/artifacts/0/doc/build/html/index.html Install first: https://output.circle-artifacts.com/output/job/861ef582-afb7-45bf-8731-aeacf78fea48/artifacts/0/doc/build/html/index.html put back shortcuts to figure/subplots/mosaic+ figure/plottting: https://output.circle-artifacts.com/output/job/865255a4-9010-4710-b26c-7b83011536aa/artifacts/0/doc/build/html/index.html Not a huge fan of the release notes but also they'll look cleaner in the released version (and trying ifconfig devel only show devel didn't work) and spent way too much time trying to figure out how to get cards aligned nicely and giving up on that for now. |
|
I agree with Jody, the content of the front page should stay about the same. I did not mean to open a discussion about radically changing what was on the front page (sorry if I communicated badly). By making that the top of the TOC I think it would smooth out a bunch of the weirdness in how we are trying to use sphinx. Can we please keep this PR to primarily doing that rotation and separate it from any drastic content changes? |
I added the sections that used to be in the user guide and made some layout changes so things would flow - and I provided 3 variants with different levels of closeness to the original. The only content change was restructuring learn to remove duplication - I didn't get rid of any links. |
|
From a UX perspective, the small changes made to the Learn section make a big difference to usability with very little visual disruption to the existing interface. Adding a few more words and differentiating |
There was a problem hiding this comment.
The reorganization makes more sense than what we had before. Glad it was relatively straight forward. I'm largely fine with the output in https://output.circle-artifacts.com/output/job/865255a4-9010-4710-b26c-7b83011536aa/artifacts/0/doc/build/html/index.html
The current version doesn't render and needs a rebase? so not 100% sure.
Other than the two major comments below, my other suggestion is that the new page is somewhat eclectic mix of cards and not cards - I can't see the reason for what is in a card and what is not in a card, so it makes it a bit confusing to my eye.
jklymak
added
the
Release critical
|
This would ideally be finished before 3.8 doc release. |
story645
force-pushed
the
doc-root
branch
2 times, most recently
from
e42e0bd
to
f879af6
Compare
|
So the existing content takes up more or less the same amount of space. I got rid of all the cards except the ones around Learn because I want to emphasize learn. Went w/ new filler text + toc instead of side by side cards cause I really wanted a navigable right hand side menu. The changes are:
|
doc/index.rst
Outdated
|
|
||
| .. raw:: html | ||
|
|
||
| <div class="grid__intro" id="image_rotator"></div> |
There was a problem hiding this comment.
This feels out of place. What does this have to do with "About"?
If you want to have something visual, I suggest to either use the matplotlib logo, or if that's too colorful here, some sort of "about icon".
There was a problem hiding this comment.
was thinking more plots are what the library is about, but could also put the old 4 panel for that
or maybe one of the EEG images as a nod to John Hunter
This is from the the IEEE and the open architecture paper:
There was a problem hiding this comment.
so eeg pic is in old docs https://matplotlib.org/3.3.4/tutorials/introductory/sample_plots.html
the advantage of using the 4 panel is it's a call back to the readme.
There was a problem hiding this comment.
was thinking more plots are what the library is about,
Yes, but plots is not what this section is about. This section is a kind of meta-section about the library itself. There are dedicatedly all non-plotting aspects, which is why I find plots inappropriate here.
More generally/aesthetically: it's a bit imbalanced that this is the only non-text entry.
There was a problem hiding this comment.
Hmm, so that's why I'm now leaning towards plots that have to do with project history (like the eeg one) or nod to the website history (the 4 panel).
Another option is maybe bringing this section all the way to the top and using the intro library text as anchoring...which honestly is why I'm not so keen on writing new anchoring text.
There was a problem hiding this comment.
:/ I hear, like maybe put that picture in the history docs. I think what could be fun is putting a rotator that pulls from the gallery images?
There was a problem hiding this comment.
The advantage of the plot type images is they are all the same size and the same style. I think pulling random Gallery images would be hard, though if you had a curated list that may work.
The plot type rotator is on the front page, but I think would be useful here as well ( drives traffic to Plot Types and shows basic functionality). I would still have it near the top.
There was a problem hiding this comment.
So yes to plot type gallery rotator next to about us, no to plot type gallery next to plot type index? I was thinking the old 4 panel for continuity, the rotator is also continuity.
The install index is wide b/c you nixed the install TOC as the side by side, but I like this layout better way b/c I think in the other tab is clearer guidance on when folks should consult that page.
There was a problem hiding this comment.
My 2 cents:
-
Rotators are ambivalent. People usually see only one sample image. They don't realize there are variants. Even if they knew, reloading to see all variants would be cumbersome. If chances are bad, they get a barbs plot and ask themselves why we have such strange plots in a prominent place. It's almost always better to have a carefully selected static image. A (carefully curated) rotator is only reasonable if we want to fill visual space without wanting to communicate anything specific beyond "hey, look, we can do nice plots". (IMHO ok on the front page, but almost nowhere else).
-
Keeping sample images for the sake continuity is not relevant. Most users will not recognize that anyway. If there is better content - visual or non-visual (including maybe no content) - that's much preferable.
There was a problem hiding this comment.
Ok, so here's a short 'history and mission of matplotlib` blurb that calls back to the second line on the brochure page. We start this page w/ the first line from the brochure, so it bookends nicely and is a lead in for most of the about content.
|
Since #26414 is in, you should be able to rebase on master to get rid of the flake8 errors. |
story645
force-pushed
the
doc-root
branch
3 times, most recently
from
eee55b8
to
f57fa70
Compare
doc/index.rst
Outdated
| Matplotlib was created by John Hunter to visualize EEG data. John's | ||
| goal was that Matplotlib make easy things easy and | ||
| hard things possible. |
There was a problem hiding this comment.
If you go into history, I suggest to span the arch to the current state
| Matplotlib was created by John Hunter to visualize EEG data. John's | |
| goal was that Matplotlib make easy things easy and | |
| hard things possible. | |
| Matplotlib was originally created by neurobiologist John Hunter to | |
| visualize EEG data. It quickly grew into a popular gerneral-purpose | |
| plotting library. John's goal was that Matplotlib make easy things | |
| easy and hard things possible. |
On a side note (please ignore as off-topic, but I have to mention this)
I still don't like the "easy things easy and hard things possible". The first part is to be expected from any reasonable tool. If you don't do this, you simply have bad user experience. IMHO that's not a mission statement worth mentioning. - It's in particular not great, as matplotlib has a relatively steep initial learning curve (partly due to our heritage) and I'd claim that e.g. plotly makes easy things easier than we do. :(
There was a problem hiding this comment.
Honestly I don't love it either which is why here I'm casting it as John's goal. I don't like it at all on the brochure site for similar reasons to yours, but since it's there lets keep continuity. Also according to the history page, the pyplot interface that we now discourage was the "make things easy"
doc/index.rst
Outdated
| Learn | ||
| ===== | ||
|
|
||
| Start at the :ref:`Quick Start <quick_start>` guide! |
There was a problem hiding this comment.
This link can be missed easily becuase it vanishes in a prose sentence between more prominent visual elements (heading and cards):
I suggest to either move this into the "How to use Matplotlib" card, or highlight it more. (But this is nitpicking)
There was a problem hiding this comment.
No I agree - used to have it in the install card but then got rid of the install card.
There was a problem hiding this comment.
also I don't like how to and troubleshooting here, but I think I'll bury it in the user guide after we sort what the guide is doing.
…sers + moved users index a level up
The use of the rotator was dropped in matplotlib#26332. Currently, it causes an exception on every page, because there is no 'image_rotator' element, but this is only visible in the console or, if you have the inspector open, it'll start the debugger.
Makes doc/index.rst the root of the doc tree, per #26156 and discussion w/ @tacaswell. I took the approach of treating it as a sorta guide to the docs, which is why there's a little preamble before each section. It irks me that the section headers aren't all in the same case, but I'm also looking for something easily right hand parseable. #26328 was opened with this in mind to give a cleaner listing for the plot type gallery.
Moving root to doc/index.rst means that user/index.rst is no longer root. Here I got rid of it and am using user_explain/index as the landing page for the user guide. Added anatomy + shortened explanation as mentioned in #26205 as a way to orient new users to the contents of the user guide.
Changes here bring the docs more in line w/ the structure proposed in matplotlib/mpl-sphinx-theme#72
attn: @esibinga and @melissawm