Gathering design feedback, from a CPython documentation build with Lutra

[pradyunsg]

I've deployed a build of CPython documentation built with Lutra. The index page is empty for now -- we can add back the content there later. The changes needed were not very invasive: python/cpython@main...pradyunsg:migrate-to-lutra

Based on a quick skim, it looks like Lutra has most of the things needed to build CPython's docs. To be clear, that does not mean it's complete -- there's quite a few more things needed here (version/language selectors, footer, mobile left sidebar contents etc). I might have also missed some piece of content, which might mean that it's stylised poorly.

I'd like to get feedback on mainly three fronts:

• Content styling (page text, tables, code, API etc) -- does something look bad, or not accessible, or doesn't function correctly?
• Navigation design (how the sidebar changes, whether segmenting docs w/ tabs might be useful, what the left sidebar should contain)
• Search Presentation (not the results themselves, but how it behaves + looks)

Lutra has additional navigation designs (i.e. tabs, different way of managing subsections), but I want to hear what folks think about the current navigation design. The other designs would require changes to CPython's Doc/contents.rst (if this design doesn't fly, we can try those!).

General feedback is also welcome. Please poke sticks at this and let me know where it breaks!

[pradyunsg]

Please don't feel obliged to go through this with a fine-tooth comb, but I certainly won't complain if someone does!

Just know that it's 4am where I am right now so... I'll respond after quite some time. :)

[pradyunsg]

And, the above link is where I've posted asking for feedback on this build.

[mwichmann]

"Navigation design (how the sidebar changes" : to me, the loss of within-page navigation in the sidebar (Table of Contents) is a big loss. I've looked at several standard library modules. The longer ones with lots of complexity really benefit from this, IMO - it's far less important to be able to navigate to someplace completely different in the docs - it's a single click to go someplace that has that (e.g. using the breadcrumbs at the top), if I need it.

Appearance-wise, dark themes always take a lot to get right (for which reason I generally hate them, but that's not feedback for here!). If you look at pathlib (https://pradyunsg-cpython-lutra-testing.readthedocs.io/en/latest/library/pathlib.html) the arrows in the diagram are gone, probably still black.

[pradyunsg]

to me, the loss of within-page navigation in the sidebar (Table of Contents) is a big loss. I've looked at several standard library modules.

Do you have specific links? There's an "On this page" section on nearly every page, which will have the same content as the "Table of Contents" in docs.python.org today. For example, the left sidebar in https://docs.python.org/3/library/pathlib.html is the same as the right sidebar in https://pradyunsg-cpython-lutra-testing.readthedocs.io/en/latest/library/pathlib.html.

I feel like I might be misunderstanding you, so if you could provide more context on what you mean by "loss of within-page navigation in the sidebar", I'd appreciate that. :)

If you look at pathlib (pradyunsg-cpython-lutra-testing.readthedocs.io/en/latest/library/pathlib.html) the arrows in the diagram are gone, probably still black.

Yea, certain pages/diagrams will need separate images for dark mode and light mode. That's a good catch -- I'll keep that in mind.

Out of curiosity, did you notice that there's a button to toggle between the dark mode and light mode? (No is a valid answer -- that'll flag to me that it's not sufficiently accessible/visible).

[mwichmann]

No, you're right... the contents links are on the right side. I freely admit that i didn't look over there any more after seeing a prominent ad, figuring that sidebar was being taken up by whatever was being inserted there by the host of the temporary site you were posting on. Lazy me.

Out of curiosity, did you notice that there's a button to toggle between the dark mode and light mode? (No is a valid answer

No - is that the moon symbol that's up in the corner now I look? And the answer seems to be yes, it is.

[pradyunsg]

Ah! I don't see the Read the Docs ads due to pi-hole, so I didn't even realise it was getting injected there. Thanks for flagging that -- I'll look into changing where the ad gets injected and how to make it not-a-block-of-white in dark mode. :)

[mwichmann]

Ah! I don't see the Read the Docs ads due to pi-hole

That reminds me, I need to rebuild my Pi, I had that wonderful tool running too; apparently the sd card has be worn out and it won't boot. (yes, now OT, sorry)

[CAM-Gerlach]

High-level comments/suggestions

• I wasn't sure at first, but I think the current approach of showing the current top-level section and the opened subsections in the left sidebar seems to be a reasonable compromise to me and the closest match to how things are structured now, at least for the initial transition. I would tend to think that exploring alternative navigation layouts is something that would be better be done In the future post-transition, especially as we consider any changes to the docs' structure,

• In the right "On this page" sidebar, I find it very helpful to have an indication of where I am in the page currently, which Furo (and our PyData-Spyder theme) does but Lutra does not appear to (yet) provide.

• Personally at least, I can't stand the UX of "search boxes" that, upon click, take me to a modal or a whole separate page before even being able to type in a search term, and then make another request to execute it. I would much prefer the conventional behavior of being able to type in the search box and the search page only being displayed once I press enter, as is currently the case with the Python docs (and Furo), since it is faster and less disruptive. Especially when search only triggers on enter, I don't really understand the reason for bringing up the search page upon merely clicking the search box when there's nothing useful on it until the user presses enter to search, it just makes an extra request, takes the user away from their current page and adds an extra entry to the forward/back history for no obvious gain. But maybe there's something I'm missing here.

Specific rendering issues

• The changelog doesn't work (I assume that's a known issue, but mentioning it just in case)

• Can the Notes and See Also admonitions have different colors, like they do in the current docs? Its much harder for the reader to tell them apart at a glance, especially since they are often found close together. Perhaps See Also could be, e.g., green?

• The "automatic" state of the dark theme button not having a separate icon, unlike Furo (and the PEPs theme, for which we shamelessly ripped off yours), was very confusing to me, and would have been even more so had I not been intimately aware of how Furo worked in this regard. I'd suggest it work like Furo and have a dedicated icon for the Automatic state. This also might be a a11y issue for color-blind or hard-of-vision users.

• On various pages, including the descriptor HOWTO and various FAQs that have custom contents:: directives, either they need to be eliminated from the source or ignored/handled.

  Screenshot

  

• The interaction of the "collapse sidebar to left" button and the sidebar scrollbar looks a little unpolished. I suggest either giving the button a background color (even something as subtle as --color-bg-header), and/or moving it to the left or right of the scrollbar.

  Screenshot

  

• The numbering combined with the lack of being sublevels under the extending and embedding section results in the sidebar for the extending and embedding section featuring discontignous, repeated numbers

  Screenshot

  

Responses

The index page is empty for now

For funsies, you could tweak the text to read "This page intentionally left blank" :D

Yea, certain pages/diagrams will need separate images for dark mode and light mode. That's a good catch -- I'll keep that in mind.

In the PEPs we handle with with adding a specific rst-class in the source to transparent graphics, diagrams, etc. that need it that uses a CSS filter to invert the SVG/PNG. Crude, but it works decently well for the purpose with minimal effort.

Ah! I don't see the Read the Docs ads due to pi-hole, so I didn't even realise it was getting injected there. Thanks for flagging that -- I'll look into changing where the ad gets injected and how to make it not-a-block-of-white in dark mode. :)

Perhaps you could host on GH pages, which doesn't inject ads (and at least IMO, previews and deploys a lot faster than RTD, and is easily portable between any CI backend?

[pradyunsg]

• In the right "On this page" sidebar, I find it very helpful to have an indication of where I am in the page currently, which Furo (and our PyData-Spyder theme) does but Lutra does not appear to (yet) provide.

Yup, need to add that. I am looking for alternatives to gumshoe for scroll-spying, to see if I can use something else.

[pradyunsg]

The numbering combined with the lack of being sublevels under the extending and embedding section results in the sidebar for the extending and embedding section featuring discontignous, repeated numbers

Indeed. I think it's reasonable to drop the :numbered: from the second toctree in this case.

The "automatic" state of the dark theme button not having a separate icon, unlike Furo

That's true, and a fair point! It's also simpler to implement it that way. :)

The interaction of the "collapse sidebar to left" button and the sidebar scrollbar looks a little unpolished.

Duly noted! I borrowed that style of collapse buttons from docasuarus, which... now that I'm looking, actually removes the scrollbar entirely. I'll have to think about what to do here now.

On various pages, including the descriptor HOWTO and various FAQs that have custom contents:: directives, either they need to be eliminated from the source or ignored/handled.

I'm gonna say that we should remove those, if we switch to a theme with a three-column layout with the toc in the sidebar. It'll be redundant and does not add any value.

I would tend to think that exploring alternative navigation layouts is something that would be better be done In the future post-transition, especially as we consider any changes to the docs' structure,

Well, I've been exploring them already. I've got 6 of them implemented -- I just don't want to distract with them, for now. :)

CSS filter to invert

Smart. I'll gonna permanently borrow that.

I would much prefer the conventional behavior of being able to type in the search box and the search page only being displayed once I press enter

Good to know. I was leaning similarly, but wasn't sure if that was a result of me having looked at this too long, or if this approach was actually suboptiomal. You've convinced me that it's suboptiomal -- thank you!

Perhaps you could host on GH pages, which doesn't inject ads (and at least IMO, previews and deploys a lot faster than RTD, and is easily portable between any CI backend?

I could -- but then it'll be on pradyunsg.me, which I didn't want to put it on. I could put it in pradyun.github.io but it's significantly easier to change where the ad shows up on the page. Besides, there's a lot of deployed-on-RTD documentation sites, and this is an excuse for me to figure out how to get those rendering properly with their injections. :)

[CAM-Gerlach]

Yup, need to add that. I am looking for alternatives to gumshoe for scroll-spying, to see if I can use something else.

Not sure if its what you're looking for, but the PyData Sphinx Theme which ours is based off of uses Bootstrap's scrollspy.

Indeed. I think it's reasonable to drop the :numbered: from the second toctree in this case.

In fact, IMO it should be dropped from both toctrees, since there isn't a clear purpose behind the ordered numbers (there isn't an inherent strict order of the sections)

I'm gonna say that we should remove those, if we switch to a theme with a three-column layout with the toc in the sidebar. It'll be redundant and does not add any value.

That was my thinking as well; should be a matter of find and replace any contents:: directives

Well, I've been exploring them already. I've got 6 of them implemented -- I just don't want to distract with them, for now. :)

That's mostly oriented not toward you and more toward avoiding inevitable bikeshedding over this delaying the implementation of the theme for the Python docs site :)

Smart. I'll gonna permanently borrow that.

See python/peps/2409 for the implementation, but its basically as simple as a custom CSS class added to the relevant images with :class: or rst-class that sets an invert CSS filter.

Good to know. I was leaning similarly, but wasn't sure if that was a result of me having looked at this too long, or if this approach was actually suboptiomal. You've convinced me that it's suboptiomal -- thank you!

It might make sense if the search was "as you type", but its not (not sure how easy/performant that would even be to implement in Sphinx), though it would still be a tradeoff that would have to be considered.

[merwok]

There are only around 10 contents directives, mostly in howtos and FAQ documents.
They are indeed technically redundant with the new local TOC in the sidebar, but I find the previous style better: it is easier to see an overview of the document with the table of contents in the main column, as there tends to be many sections with sometimes long titles. The right sidebar is not found as easily, requires scrolling and has smaller text. So maybe an exception for documents that use the contents directive could be a good thing.

Other notes about the new TOC sidebar:

• not present on mobile
• on desktop, text wrapping in the right sidebar changes when the scrollbar is displayed or not, making the text jump in a jarring way and possibly changing where you were going to click

[pradyunsg]

There is mechanism to have the contents directive to be "exempted". The message on pages with that content states as much.

not present on mobile

Yup, this isn't implemented yet.

IIRC, I need to add the button to present the drawer that contains this -- the reason this stalled was because I wasn't sure if I want to make the left sidebar more aware (like mkdocs-material) or just add a right sidebar for this (like Furo).

making the text jump

Ooooh! Nice catch. I have overlay scrollbars, so it's unlikely I'd have seen this. I remember doing something hacky for this in Furo -- I'll have to go back and look. :)

[merwok]

There is mechanism to have the contents directive to be "exempted". The message on pages with that content states as much.

I don’t think I understand what you’re saying.

In case it wasn’t clear, what I was saying is: for pages with contents directive, don’t add the right sidebar.

[pradyunsg]

Ah, I definitely misunderstood you. I think that's a bad idea, but I'm not going to be blocking people who'd want to do that though -- it's possible already via a per-file metadata attribute (:no-toc: at top of file)

[CAM-Gerlach]

on desktop, text wrapping in the right sidebar changes when the scrollbar is displayed or not, making the text jump in a jarring way and possibly changing where you were going to click

I can't seem to repro this on FF 97 on Windows, where I have overlay scrollbars, but given they are an still somewhat unstandardized and unevenly implemented feature across browsers and platforms, I imagine they are handled differently on your browser/platform. After testing them on the PEPs repo on various users and platforms, I ended up reverting to standard scrollbars for now to ensure consistent, reliable behavior across browsers and OSes. It doesn't look nearly as good, but it avoided several issues we ran in to (I don't have the details OTTOMH).

[Mobile stuff] Yup, this isn't implemented yet.

Just to clarify, I didn't review responsiveness at smaller screen widths in the above set of comments, to avoid making my comment even longer and more nitpicky especially if that wasn't all ready yet, but I can do another pass when that's ready @pradyunsg

In case it wasn’t clear, what I was saying is: for pages with contents directive, don’t add the right sidebar.

There's an argument to be made for including the ToC near the top in these cases (at least in the FAQs) for the reasons you mentioned, albeit at the cost of requiring more scrolling to get to the actual content (though for something like an FAQ, this isn't so much of an issue). However, I'm not sure there's a strong reason to hide the right sidebar completely; that would leave the user no way of easily knowing where they are in the document, and no way of quickly navigating through it, which would be a regression on the current docs which do still display the document contents in the sidebar in addition to the ToC at the top.

[gunungpw]

Small issue, the "navigations hide button", blocked by bread crumb section when scrolling;


it's intentional?

[pradyunsg]

No, and that's fixed in a commit since I built the preview of the CPython docs.