docs/lib: generalise using the module system

[MattSturgeon]

This PR introduces a new way of managing docs pages, inspired by work in #2884.

The end goal is to entirely replace docs/mdbook/default.nix with an overall simpler* implementation that creates fewer derivations and uses more upstream tooling, such as lib.options.optionAttrSetToDocList.

* or at least, more understandable, modular, maintainable

The naive implementation may simple wish to directly apply lib.options.optionAttrSetToDocList to the full options set, and then group that list into "pages" of options. This approach seems simple at first, however it quickly gets complex when you want to turn that set of pages into a mdbook summary menu.

This PR takes an opposite approach. We start by defining the menu, and then decide later what goes on each page.

---

To minimise the scope of this PR, it does not aim to replace all docs pages yet. Instead, it only replaces the "lib docs" implementation for now.

That said, it does include scope for rendering options in its module scheme. There's no option-doc-rendering code yet, but I have laid out things like _page.options where we would list which options to include on that particular page.

---

Another thing that is out-of-scope for now is including these docs-creating modules within the main nixvim module set. This will be possible, but isn't done here as a) it isn't fully finished and b) I want to minimise scope creep.

When this is done, we will be able to use the extendModules module arg to re-evaluate the outer nixvim configuration with different specialArgs (etc). This is useful for ensuring we don't accidentally rely on things like pkgs or config in our documented defaults/examples/etc.

---

High level overview

In docs/modules/menu.nix, a MDBook menu is represented as a freeform attrset of "category" submodules. Alongside these "categories" is a special _menu option set, where explicit options can live. This "menu" represents the entire SUMMARY.md file.

In docs/modules/category.nix, each "category" is itself an attrset of "page" submodules. Alongside these pages is a _category options set, where category metadata is defined. A category represents what MDBook calls a "part".

In docs/modules/page.nix and docs/modules/page-options.nix, each "page" is itself represented as an attrset of sub-pages. This is a recursive tree structure. Each page node also has a _page option set, where page metadata can be defined.

When rendering the menu, we start in menu.nix by sorting and ordering the categories, then simply concatenating each category's menu. In category.nix, we render the categories menu by concatenating each page's menu. In page-options.nix, we render a page's menu by printing the markdown for the specific page node and concatenating all sub-page's menus recursively.

There's a little complexity when rendering menus:

1. Pages that only have one child and don't have any content of their own should be "absorbed" into the child menu entry
   • This is handled by the showInMenu boolean
2. Pages should omit their parent page's menu text from their own menu text
   • This is handled by representing menu text as a loc path and removing the parent (prefix) path.
3. Pages that are part of a "prefix" or "suffix" category should not use - list syntax and can't render as nested.
   • This is handled by the nested boolean

See https://rust-lang.github.io/mdBook/format/summary.html

[traxys]

Ah so this means that we can "easily" add documentation "anywhere" in the module system, right?

[MattSturgeon]

Yeah. I tried to come up with a structured way of representing a mdbook menu tree.

There are other possible approaches. E.g. we could have a flat structure with each element having a "loc" attribute.

[traxys]

This seems indeed much simpler to understand! It was pretty clear to me, and it’s been some time since I was really involved, thanks a lot!

[MattSturgeon]

Thanks @traxys for your review! I would've liked more reviews and/or feedback from @GaetanLepage and @khaneliman, but I'm going to merge this later today to avoid it getting stale.

[khaneliman]

Sorry, just deadline swamped at work so have no energy for in depth reviews atm. I trust your work, though.