Biased for smaller docsets?

[FernandoBasso]

The README says:

Biased for smaller docsets --- intended for smaller documentation sets, where presenting the entire hierarchy in the sidebar is not overwhelming.

Why is that? What does Furo lacks or does in some way that makes it biased for smaller docsets? What would have to be different to make it less biased and suitable for larger docsets?

[pradyunsg]

What does Furo lacks or does in some way that makes it biased for smaller docsets? What would have to be different to make it less biased and suitable for larger docsets?

Two main things:

• The entire site structure is presented in the sidebar -- if you have a big documentation set, all your pages get correspondingly large as well.
• There is only one layer of navigation -- there's no separation to enable separate "sections" in your documentation site (eg: https://squidfunk.github.io/mkdocs-material/getting-started/, https://docs.github.com/en/get-started).

[FernandoBasso]

Thanks for your response, @pradyunsg. The examples were very clarifying too.

I think it may be worth providing some context around my original question.

I have notes and tutorial-like stuff ranging from POSIX stuff, command line and shell script to C, Haskell and many other languages. Algorithms, exercises solutions from books, etc. I have been accumulating these for about 12 years now. I have always used a mix of Org-mode, Markdown, Asciidoctor and the Zim Wiki Desktop on Linux.

Zim Wiki is especially practical, easy to use, very configurable, and for me, the most important, searchable and navigable. It has a left-side bar with pages and subpages, and a table of contents (position is configurable, but I always use it on the right side).

I'm trying to use Sphinx for the second time (the fist was about 5 years ago, I think) to move my personal notes about programming and development in general. I didn't like how little navigable things were (for several reasons I won't go into here).

I discovered Furo theme reading Kitty's docs and immediately fell in love with it ❤️. You rocked!!! Gosh this theme looks nice! It is INDEED VERY NAVIGABLE precisely because of the left and right sidebars (and it does work amazingly well on mobile too). For me, the left and side bars with pages and headings navigation is a MUST, and Furo has done it in a perfect way! Brilliant work!

My intent is to slowly move all my notes (and write future notes) to Sphinx and Furo seems to be working really fine. I think on the left sidebar I'll have main pages like Shell, Haskell, JavaScript, C, TDD and a few (perhaps many) others. The idea is to have fewer top pages, and stick "subcategories" under them, with further subpages (subcategories), depending on how it feels for each case.

Here's how I have been doing it so far. I barely started migrating stuff, and my time is limited. There's also a question and answer thing I'm trying to do. More polishing is needed but it already proves it works.

Not related to Furo's itself, but writing in reST has been a pleasure. It is a powerful markup language, clean enough to read in source form, and emacs rst-mode does an amazing job (I use multiple editors, vim and emacs being my preferred ones. So far, emacs has proven invincible when it comes to reST 🙂). I mention this because just presenting content is one thing, but having a nice, practical and pleasurable workflow to produce it is also important.

Anyway, this is a brain-dump of my ideas so far. Not sure if these considerations warrant or require an answer (but feel free to provide thoughts or insights if you feel inclined to do so). Just wanted to share these thoughts and give context on the original question.

Thanks a lot for your awesome work on this theme!

[astrojuanlu]

To be honest, I see no practical difference between Furo navigation, MkDocs material, and the GitHub docs. Yes, eventually I'm adopting Furo for every personal project, big or small :)

[pradyunsg]

I'm glad you like this! ^.^

Providing clearer navigation was definitely one of the goals while writing this theme. :)

If I may say so myself, Furo does a better job than a substantial portion of the "competition" in this space. Even then, I still feel that having an additional layer of navigation is essential for large multi-part documentation, especially if you want to consolidate things under the same banner.

Most Sphinx documentation solves that by having an in-page ToC in many cases, but I do think that it's possible to do a better job than that within the constraints of Sphinx. I just need enough free time to tackle that. :)