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.
`internal` options are intended to be implicitly not `visible`. This is
already handled correctly by the nixos tooling, but our custom tooling
did not correctly handle the edge case.
This lead to strange cases where an internal option is not included in
the docs, but its sub-options were still visible.
Add a non-system specific `<flake>.lib.nixvim` output, which is
equivalent to the existing `<flake>.lib.<system>.helpers` output.
This is now also wrapped with `lib.makeOverridable` to allow overriding
the function args used to construct the nixvim-lib.
Consistently access nixvim-lib via the new flake output, overriding
where necessary.
