docs/lib: generate function docs from RFC145 doc-comments #3049
Conversation
MattSturgeon
changed the title
MattSturgeon
force-pushed
the
docs/lib
branch
3 times, most recently
from
d350654 to
341f475
Compare
MattSturgeon
force-pushed
the
docs/lib
branch
3 times, most recently
from
1cea135 to
9ce2d4b
Compare
| @FUNCTIONS_MENU@ | ||
|
|
There was a problem hiding this comment.
I originally put this higher up because the old helpers.md guide was near the top. However, it'd also be valid to have "Functions Reference" section after the "Options" reference section, if preferred.
Thoughts?
|
LMK if there's anything I can do to make this easier to review, or any parts that could be reviewed separately in another PR. |
MattSturgeon
force-pushed
the
docs/lib
branch
2 times, most recently
from
1fde7a4 to
9063a4d
Compare
|
Everything looks pretty good to me stepping through commits. One thing that I was curious about was the separation of internal v public lib api. Is it just supposed to be to help document the most common lib functions that help with creating a config? |
🎉
Before this PR I was hesitant to add "internal" functions to the docs. I was also hesitant to remove rfc145 doc-comments from internal functions. My workaround was to split the file into public & internal files. This is kinda ugly and ham-fisted, but it works... I'm not toatally opposed to having docs for internal functions too, but I think that should be addressed separately and clearly separated/hidden away in the docs. Anything we publicly document we're kinda saying "this is our public API, this is kinda stable and won't change without warning" so we should be careful which functions are documented publicly, just as we are careful which options are visible/hidden/internal. |
This makes more sense to me about why we're being so conservative in the documentation. Thank you, I agree we should start slimmed down with the |
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
Embed the function reference docs into the main docs website.
Move the user-guide to the new lib reference docs. Added a MDBook redirect entry. Updated man docs.
Like options, function docs are large. Let's put them after the FAQ and config-examples sections
Move heading to `pages.nix` page title.
We will include the public file in the docs.
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.
| # Normalise a page node, recursively normalise its children | ||
| elaboratePage = | ||
| loc: | ||
| { | ||
| title ? "", | ||
| markdown ? null, | ||
| file ? null, | ||
| pages ? { }, | ||
| }@page: | ||
| { | ||
| name = lib.attrsets.showAttrPath loc; | ||
| loc = lib.throwIfNot ( | ||
| builtins.head loc == "lib" | ||
| ) "All pages must be within `lib`, unexpected root `${builtins.head loc}`" (builtins.tail loc); | ||
| } | ||
| // lib.optionalAttrs (shouldRenderPage page) { | ||
| inherit | ||
| file | ||
| title | ||
| ; | ||
| markdown = | ||
| if builtins.isString markdown then | ||
| builtins.toFile "${lib.strings.replaceStrings [ "/" "-" ] (lib.lists.last loc)}.md" markdown | ||
| else | ||
| markdown; | ||
| outFile = lib.strings.concatStringsSep "/" (loc ++ [ "index.md" ]); | ||
| } | ||
| // lib.optionalAttrs (page ? pages) { | ||
| pages = elaboratePages loc pages; | ||
| }; |
There was a problem hiding this comment.
I believe we could simplify this by using the module system to evaluate pages.nix.
Most of this "normalisation" could be done by a page submodule.
I'll plan to address this in a follow up PR.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
This pull request, with head sha This pull request will be automatically closed by GitHub.As soon as GitHub detects that the sha It is possible for this pull request to remain open if this detection does not happen, this usually happens when a force-push is done on this branch |
Add auto-generated reference docs for nixvim's public functions, inspired by nixpkg's lib docs.
Uses
nixdocto print RFC145 doc-comments from a given input file to a markdown file. This is very similar to:docin the repl, but there are subtle differences.docs/lib/pages.nixdescribes which files to document.All docs are included on both the website and man page.
TODO
user-guide/helpers->lib/index)lib.nixvimshould go in the docsScreenshot