Refactor `serve-docs` using `makeWrapper`, make it available as a
`serve-docs` package and as the `docs` "app".
This means `nix build .#docs` will build the docs while `nix run .#docs`
will run the server.
Moved all function-specific docs from `docs/lib/index.md` into RFC145
doc-comments.
Added `lib.nixvim.lua.toLuaObject` to hold the public docs and serve as
a stable impl of `toLua'` in case we decide to change its defaults.
Generate reference docs for functions that have RFC145 style
doc-comments.
1. function locations
`docs/lib/function-locations.nix` scans nixvim's extended lib,
extracting "position entries" via `unsafeGetAttrPos`.
This is then converted into a nixdoc `locations.json` map of
"function name" → "markdown location string".
2. mdbook menu
`docs/lib/menu.nix` renders a mdbook menu representing all page
entries.
3. markdown pages
`docs/lib/default.nix` expects a set of "page entries", which come
from `docs/lib/pages.nix` by default. It passes this data to
`function-locations.nix` and `menu.nix`, and uses it internally to
render markdown pages.
Page entries can contain a `file` to render using `nixdoc`, and also a
`markdown` attribute which will be included at the top of the docs.
Additionally, a `title` can be included. This forms the heading
`$name: $title`, where `name` is derived from the page's attr-path.
See https://github.com/nix-community/nixdoc
- Strip trailing `?query` and/or `#anchor`
- Strip leading `./` recursively
- Check if what's left is `""` or `"."`
Any link that targets the current page should be left as-is (no-op).
We are essentially writing GFM e.g. inline HTML comments and GFM alerts.
So tell pandoc to parse/render as such. This resolves issues such as:
`> [!TIP]` being escaped to `> \[!TIP\]`.
The README/CONTRIBUTING files are authored with GitHub in mind, but we
want to re-use them for the docs website.
Replace the existing simple substitution with a pandoc AST-based filter.
Replace the `package-options` test with a stricter implementation.
When evaluating modules for use in the docs, provide them with a stubbed
`pkgs` instance that throws an error whenever a package is evaluated.
This ensures we don't accidentally use any packages in defaults or
examples.
