Document "fmt: off" under Usage, docs site is hard to use

[hauntsaninja]

I found myself wanting to turn black off for a block of code, so I searched my brain and it came up with # format: off. This didn't work, so I looked up black's docs. I went to: https://black.readthedocs.io/en/stable/ from which I clicked on "Usage and Configuration" from which I clicked on "The basics" from which I expanded some drop downs (whose content isn't searchable until expanded), which led me nowhere. This is a lot of clicks and no result compared to the old days when everything was in the README.

So I guess I have the following asks:

1. Document # fmt: off in Usage (grep tells me it's currently in a section called "The Black code style", which itself is two clicks away from the docs home page)
2. Flatten the docs site a little. Unlike the totally flat README in the old days, it seems to take a lot of clicks to go anywhere and you can't use browser search to find what you're looking for. E.g., there's no reason to make users click again for a page like this: https://black.readthedocs.io/en/stable/usage_and_configuration/index.html

Thanks and feel free to ignore if you disagree! :-)

[ichard26]

Document # fmt: off in Usage

+1

RE: Flatten the docs site a little.

I will admit that those two clicks have been annoying to me too (and I'm the one responsible for this change!). For this issue, I can think of three possible solutions:

• Flatten the docs: I don't really want to do this mostly because I'm tired of making structural changes. I'm also not sure whether combining all of the docs in Usage section into one document (or alternatively putting all of them top-level like before) is a good idea.
• Switch to another HTML theme: I prefer this one for two reasons, 1) I don't have to make another structural PR, and 2) it would sidestep Alabaster's lack of mobile support. A caveat is that two clicks would still be needed, but instead of two full page loads, one click would be to open a section dropdown, and next click would be load the actual wanted page. Furo and ReadTheDocs both come to mind as possible themes. The main issue with this one is that this also affects branding and I don't think I have the authority to really influence that myself.
• Add some sort way to reference the nested pages from the index page: This is basically a hack to make navigating from the main page to some specific document less painful. Works but clunky and doesn't help if you're not on the main page.

My guess at how this oversight happened is that I modelled my work against Pip's documentation and their theme provides a dropdrop for each section making the structure IMO pretty easy to navigate. Unfortunately Alabaster doesn't and yep that makes this structure rather annoying.

Sorry y'all, this is very much on me for missing this :/ Thanks for bringing this up.

[ichard26]

Looking at the mypy docs, the sidebar TOC works pretty well with RTD theme to have all of the documented in the sidebar. IIRC from testing this doesn't look or feel great with Alabaster. This is basically a specific combo of 1 + 2.

[felix-hilden]

This is a lot of clicks and no result compared to the old days when everything was in the README.

Just to set a baseline, I think Richard's documentation restructuring was vital. Having everything in one place is much harder to read if you don't know what you're looking for.

-- you can't use browser search to find what you're looking for.

Also, Sphinx documentation does have a search bar! That being said:

1. Document # fmt: off in Usage

This seems entirely reasonable! I'd expect it to be there as well. We could of course have a mention in the style docs.

2. Flatten the docs site a little.

I agree that the Style and Usage top pages are a bit short, and maybe they could be converted to a single page with sections from the current pages. But I'm not a 100 % on this. Needs some thinking about what would be the best way of doing it. But overall I think reducing clicks is an important goal 👍

Switch to another HTML theme

While I like the bit of personality that comes from not using RTD, it is a great theme! Don't know about Furo, but I'm all for changing the theme for the better. The dropdowns on RTD are a bit hard to hit in my opinion:

But then again, it doesn't really reduce clicks, because the dropdown isn't exploded automatically when clicking on the top level. Would get rid of loading the page though, yeah.

Add some sort way to reference the nested pages from the index page

The :hidden: directive can be removed from indices to produce the full TOC tree. So maybe pages like this would be good (I also added :maxdepth: 2):

This could call for some restructuring though. Maybe more sections with more specialised names. A single file would be quite easy to navigate from here as well.

Works but clunky and doesn't help if you're not on the main page.

Well we could have the full full TOC on the main page, but that's messy too in my opinion 😅 Nevermind, I misread it!

Pip's documentation -- provides a dropdrop for each section

Yeah those dropdowns are pretty nice 👌

[hauntsaninja]

Thanks both! For what it's worth, I'd be in favour of converting the Style and Usage sections to a single page, but trust y'all to do what makes sense for black.

One note about pip's docs is their user guide is basically one big page with a floating TOC. The "Commands" section has the dropdown and splits, but not sure that's the best fit for black: after all, black serves a single, simple purpose, and doesn't really have subcommands with separate functionality.

[ichard26]

Yeah, you've got a point for almost everything you're saying (I kinda disagree on the comment on pip's Commands vs Black's docs).

As I've said before, I'm tired of documentation restructuring and I don't remember how moving to a single page per section would feel (from testing) and don't really feel doing it, but I will since I'm scared of managing to mess it up on the third try. TBH I'm a bit hesitant on such changes because I feel like such a "attempt #3 PR" would make me seem incompetent at doing docs, which I guess I maybe am, but then again, there's a problem to solve so that's probably moot :)

I would be half-fine flattening it if it weren't for the Blackd docs. FTR, I want to add subcommands to blackd (I saw dmypy and realized that proper support for just running a server instance of a tool is not enough and an easy client is also necessary) so there's a good chance its docs will grow. I don't really feel like adding blackd's docs to the sidebar TOC again, even with the aforementioned changes because it feels too specific and niche to deserve such a placing. Decluttering and removing stuff from the sidebar TOC was literally one of the main reasons for the restructuring in the first place. But, making Usage single-page would break that (I thought of moving blackd's docs to a guide, but that still feels weird).

Also in general, extensibility was another goal (in my original plan, there's some pages that don't exist but would live under these sections - although I do think some of them are no longer a good idea) and adding sections was to allow for that ... unfortunately they kill the UX (which is why we're here). I feel like a lot of limitations are here *because* the Alabaster theme really limits us in what structures feel and look good (forgetting about maintenance). Going the mypy route is not great since sections aren't IMO handled well (we even had to add custom CSS to support scrolling in the sidebar!) and pip commands' style (which I like obviously, although mypy is nice too) sucks currently. The TOCs provided by Furo (pip's theme) are additionally quite nice! While I'm realizing moving a new theme might not fully fix this issue, it would open up the choices (also would make this issue less of an issue for sections that I'm -1 on flattening like Guides).

Maybe it's just me but I find it hard to read pip's user guide because there's just *so* *much* text thrown at you *at* *once*. I can see it's great when referring to it as a reference, but learning on how to use the tool looks a bit frustrating (I know pip isn't really a tool you learn, but Black is small enough where it would be reasonable to teach users on its features).Yes, I now see the problems with trying to make some piece of docs double as both a guide and a reference.

I'll go and implement a few different solutions locally and come back with my observations and my (hopefully now educated) opinions, but I do wish this was less annoying :/ Hopefully I find something to sort out the Blackd wrinkle.

I trust y'all to do what makes sense for black.

I don't know if I can be trusted with this at this point 🙃 but I'll try to do better!

[hauntsaninja]

First and foremost, I think you're doing great! And in case I mismanaged my words, I'm sorry if anything I said came off sounding too critical — most of why I opened this issue was the relatively straightforward "ask 1".
That is, I agree with Felix's point about baselines; while I lack context around previous changes and decisions to the docs, I really do appreciate all the work that's gone into making black an accessible tool. It's clear that you care a lot and have thought a lot about how to make docs as helpful as possible, so trust us users have in you is very much earned :-)

[ichard26]

OK so via the power of procrastination (and then some thoughtful discussion with some members of the community on PyDis) I have warmed up to the general flattening idea and this is the summary that the discussion reached:

OK, in summary in terms of structural changes:

• merge the usage and configuration content into one page
• move blackd to integrations
• possibly change a few headers to be more descriptive

that sounds OK to me - will need a fair bit of redirects though to avoid so much churn

https://discord.com/channels/267624335836053506/846434317021741086/868552799162609744

There's a lot of other good stuff before that message but the TL;DR is that it is now time to convince myself this project is more important than working on blackbench and do some testing and get a PR up :)

First and foremost, I think you're doing great! And in case I mismanaged my words, I'm sorry if anything I said came off sounding too critical

Nah, don't worry about it, I tend for perfection so it's quite frustrating to see stuff to be less helpful / useful than I'd have hoped. Add in some general frustration and being tired with the docs and you got a probably overly expressive me :P Thanks for the compliment and thank you for maintaining mypy, my work on Black depends on it heavily via mypyc!

[cobaltt7]

I haven't found the docs to be hard to use, but I agree that the two clicks often feel excessive.

My proposed solution, which I don't see mentioned here already, would be to merge the bulk of the the_basics.md pages with the index pages. When I click on "Contributing", I expect to see an overview of contributing, which is currently in the_basics.md. Similar situation with "Usage and Configuration" (option documentation could probably stay on another page). I don't think any change is necessary for Guides or Integrations, since a list of the available guides or integrations is expected.

Would a PR for this be accepted?