Is furo right for me?

[Jackenmen]

Note: This isn't a bug or feature request for furo, just a discussion about me trying to adopt furo and wanting to see someone's opinion on this.

I've been trying to adopt furo for a while but I'm still not sure it's right for me (I like the theme so I'm not giving up yet, but I do feel like I need more ideas). Lately, I've been struggling with making documentation for groups of commands (for a discord bot, but for the sake of this discussion, you can probably treat them as cli commands, a LOT of cli commands) look good and readable.

Just switching themes isn't enough for the documentation I already have - it is hard to differentiate between sections (headers) in those documents. I feel that the uppercasing doesn't look quite right when nesting headers in my scenario, though I think that in other documents it wasn't really a problem.
Here's a Bank user guide for example:

• RTD theme: https://docs.discord.red/en/latest/cog_guides/bank.html
• furo theme: https://jack1142-red-prs.readthedocs.io/en/v3-some_furo_stuff/cog_guides/bank.html

So I've been thinking, what can I do to improve this? My first thought was to use block quotes. They nicely indicate what's part of the section but it comes at a cost of making the text italic and still leaves the uppercase header which seems even more off-putting now that you can more easily differentiate between sections.
Here's an example of how that looks on the Admin user guide (RTD example doesn't use block quotes - it just serves as a comparison to what I currently have in my docs):

• RTD theme: https://docs.discord.red/en/latest/cog_guides/admin.html
• furo theme: https://jack1142-red-prs.readthedocs.io/en/v3-some_furo_stuff/cog_guides/admin.html

When looking through Quick reStructuredText document, I've noticed one more alternative that had the potential of being right for me, field lists! It definitely does seem like an improvement over the original document - the indentation plays a big role here but I'm still not fully convinced by it. I kind of wonder if it would be better if there was additional indentation for the contents of the section (kind of similar to function documentation I suppose). And there's also those uppercase headers again 🤔
Here's an example of how that looks on Alias user guide (RTD example doesn't use field lists - it just serves as a comparison to what I currently have in my docs):

• RTD theme: https://docs.discord.red/en/latest/cog_guides/alias.html
• furo theme: https://jack1142-red-prs.readthedocs.io/en/v3-some_furo_stuff/cog_guides/alias.html

For completeness, I've also tried joining both of these approaches, but I feel it is mostly the same as it would have been with just block quotes:

• RTD theme: https://docs.discord.red/en/latest/cog_guides/cleanup.html
• furo theme: https://jack1142-red-prs.readthedocs.io/en/v3-some_furo_stuff/cog_guides/cleanup.html

---

So, this has been my journey so far, now I have finally reached a point where I'm not sure what I should do next. I certainly have a few options. I could use one of the solutions I've come up with, I could keep looking for more (which I guess I'm kind of doing by posting here right now 😄), I could try a different theme (but what theme is as cool as this one ❤️), or I could stick to the RTD theme (though I'm sure that would put-off a few dark theme enthusiasts 🙂). What do you think?

[pradyunsg]

There's been substantial changes to typography since this was filed, so I'm gonna say that this got resolved over time. :P

If there's still unresolved bits here, please feel welcome to write more comments here (i.e. not as a reply to this one).

but what theme is as cool as this one ❤️

❤️