Skip to content

Commit

Permalink
Merge pull request #177 from NotAShelf/nixos-option-docs
Browse files Browse the repository at this point in the history
docs: use nixosOptionDocs
  • Loading branch information
NotAShelf authored Nov 6, 2023
2 parents e498331 + f27ab70 commit 7bcfea2
Show file tree
Hide file tree
Showing 17 changed files with 101 additions and 36 deletions.
80 changes: 70 additions & 10 deletions docs/default.nix
Original file line number Diff line number Diff line change
Expand Up @@ -29,25 +29,68 @@
];
};

githubDeclaration = user: repo: subpath: let
urlRef = "main";
in {
url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}";
name = "<${repo}/${subpath}>";
};

dontCheckDefinitions = {_module.check = false;};

nvimModuleDocs = nmd.buildModulesDocs {
nvimPath = toString ./..;

buildOptionsDocs = args @ {
modules,
includeModuleSystemsOptions ? true,
...
}: let
options = (lib.evalModules {inherit modules;}).options;
in
pkgs.buildPackages.nixosOptionsDoc
({
options =
if includeModuleSystemsOptions
then options
else builtins.removeAttrs (options ["_module"]);
transformOptions = opt:
opt
// {
# Clean up declaration sites to not refer to local source tree
declarations =
map
(decl:
if lib.hasPrefix nvimPath (toString decl)
then
githubDeclaration "notashelf" "neovim-flake"
(lib.removePrefix "/" (lib.removePrefix nvimPath (toString decl)))
else decl)
opt.declarations;
};
}
// builtins.removeAttrs args ["modules" "includeModuleSystemsOptions"]);

nvimModuleDocs = buildOptionsDocs {
modules =
import ../modules/modules.nix {
import ../modules/modules.nix
{
inherit pkgs lib;
check = false;
}
++ [scrubbedPkgsModule dontCheckDefinitions];
moduleRootPaths = [./..];
mkModuleUrl = path: "https://github.com/notashelf/neovim-flake/blob/main/${path}#blob-path";
channelName = "neovim-flake";
docBook.id = "neovim-flake-options";
++ [scrubbedPkgsModule];
variablelistId = "neovim-flake-options";
};

docs = nmd.buildDocBookDocs {
pathName = "neovim-flake";
projectName = "neovim-flake";
modulesDocs = [nvimModuleDocs];
modulesDocs = [
{
docBook = pkgs.linkFarm "nvim-module-docs-for-nmd" {
"nmd-result/neovim-flake-options.xml" = nvimModuleDocs.optionsDocBook;
};
}
];
documentsDirectory = ./.;
documentType = "book";
chunkToc = ''
Expand All @@ -65,7 +108,24 @@
'';
};
in {
options.json = nvimModuleDocs.json.override {path = "share/doc/neovim-flake/options.json";};
manPages = docs.manPages;
options.json =
pkgs.runCommand "options.json"
# TODO: Use `nvimOptionsDoc.optionsJSON` directly once upstream
# `nixosOptionsDoc` is more customizable
{
meta.description = "List of neovim-flake options in JSON format";
} ''
mkdir -p $out/{share/doc,nix-support}
cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/neovim-flake
substitute \
${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
$out/nix-support/hydra-build-products \
--replace \
'${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
"$out/share/doc/neovim-flake"
'';

inherit (docs) manPages;

manual = {inherit (docs) html htmlOpenTool;};
}
2 changes: 1 addition & 1 deletion docs/man-configuration.xml
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,6 @@
<para>
You can use the following options in your neovim configuration.
</para>
<xi:include href="./nmd-result/neovim-flake-options.xml"/>
<xi:include href="./nmd-result/neovim-flake-options.xml" xpointer="neovim-flake-options"/>
</refsection>
</refentry>
3 changes: 1 addition & 2 deletions docs/manual.xml
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@
<xi:include href="manual/hacking.xml"/>
<appendix xml:id="ch-options">
<title>Configuration Options</title>
<xi:include href="./nmd-result/neovim-flake-options.xml" />
<xi:include href="./nmd-result/neovim-flake-options.xml" xpointer="neovim-flake-options" />
</appendix>
<xi:include href="./release-notes/release-notes.xml" />
</book>
3 changes: 2 additions & 1 deletion docs/manual/hacking.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ For example:
[source,nix]
----
# parent modules should always be unfolded
# which means module = { value = ... } instead of module.value = { ... }
module = {
value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
Expand Down Expand Up @@ -202,7 +203,7 @@ without any error messages (you can check the output of `:messages` inside neovi
your changes are good to go. Open your pull request, and it will be reviewed as soon as posssible.

If it is not a new module, but a change to an existing one, then make sure the module you have changed is enabled in the
maximal configuration by editing configuration.nix, and then run it with `nix run .#maximal -Lv`. Same procedure as
maximal configuration by editing `configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same procedure as
adding a new module will apply here.

[[sec-keybinds]]
Expand Down
5 changes: 5 additions & 0 deletions docs/release-notes/rl-0.5.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,11 @@ https://github.com/notashelf[notashelf]:

* Added `nvim-docs-view`, a plugin to display lsp hover documentation in a side panel

* Switched to `nixosOptionsDoc` in option documentation.
To quote home-manager commit: "Output is mostly unchanged aside from some minor typographical and
formatting changes, along with better source links."


https://github.com/jacekpoz[jacekpoz]:

* Fixed scrollOffset not being used
Expand Down
1 change: 0 additions & 1 deletion lib/default.nix
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,5 @@
booleans = import ./booleans.nix {inherit lib;};
types = import ./types {inherit lib;};
languages = import ./languages.nix {inherit lib;};
nmd = import ./nmd.nix;
lua = import ./lua.nix {inherit lib;};
}
1 change: 0 additions & 1 deletion lib/stdlib-extended.nix
Original file line number Diff line number Diff line change
Expand Up @@ -70,5 +70,4 @@ in

# For forward compatibility.
literalExpression = super.literalExpression or super.literalExample;
literalDocBook = super.literalDocBook or super.literalExample;
})
1 change: 1 addition & 0 deletions lib/types/plugins.nix
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,7 @@ with lib; let
options = {
package = mkOption {
type = pluginType;
description = "Plugin Package.";
};
after = mkOption {
type = listOf str;
Expand Down
2 changes: 1 addition & 1 deletion modules/autopairs/nvim-autopairs/nvim-autopairs.nix
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ with builtins; {
map_cr = mkOption {
type = types.bool;
default = true;
description = nvim.nmd.asciiDoc ''map <CR> on insert mode'';
description = ''map <CR> on insert mode'';
};

map_complete = mkOption {
Expand Down
13 changes: 6 additions & 7 deletions modules/completion/nvim-cmp/nvim-cmp.nix
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ with builtins; {
};

sources = mkOption {
description = nvim.nmd.asciiDoc ''
description = ''
Attribute set of source names for nvim-cmp.
If an attribute set is provided, then the menu value of
Expand All @@ -40,23 +40,22 @@ with builtins; {

formatting = {
format = mkOption {
description = nvim.nmd.asciiDoc ''
description = ''
The function used to customize the appearance of the completion menu.
If <<opt-vim.lsp.lspkind.enable>> is true, then the function
If [](#opt-vim.lsp.lspkind.enable) is true, then the function
will be called before modifications from lspkind.
Default is to call the menu mapping function.
'';
type = types.str;
default = "nvim_cmp_menu_map";
example = nvim.nmd.literalAsciiDoc ''
[source,lua]
---
example = lib.literalMD ''
```lua
function(entry, vim_item)
return vim_item
end
---
```
'';
};
};
Expand Down
10 changes: 5 additions & 5 deletions modules/core/default.nix
Original file line number Diff line number Diff line change
Expand Up @@ -27,23 +27,23 @@ with builtins; let
mapConfigOptions = {
silent =
mkBool false
(nvim.nmd.asciiDoc "Whether this mapping should be silent. Equivalent to adding <silent> to a map.");
"Whether this mapping should be silent. Equivalent to adding <silent> to a map.";

nowait =
mkBool false
(nvim.nmd.asciiDoc "Whether to wait for extra input on ambiguous mappings. Equivalent to adding <nowait> to a map.");
"Whether to wait for extra input on ambiguous mappings. Equivalent to adding <nowait> to a map.";

script =
mkBool false
(nvim.nmd.asciiDoc "Equivalent to adding <script> to a map.");
"Equivalent to adding <script> to a map.";

expr =
mkBool false
(nvim.nmd.asciiDoc "Means that the action is actually an expression. Equivalent to adding <expr> to a map.");
"Means that the action is actually an expression. Equivalent to adding <expr> to a map.";

unique =
mkBool false
(nvim.nmd.asciiDoc "Whether to fail if the map is already defined. Equivalent to adding <unique> to a map.");
"Whether to fail if the map is already defined. Equivalent to adding <unique> to a map.";

noremap =
mkBool true
Expand Down
1 change: 1 addition & 0 deletions modules/filetree/nvimtree/nvimtree.nix
Original file line number Diff line number Diff line change
Expand Up @@ -580,6 +580,7 @@ with builtins; {

icons = mkOption {
type = types.attrs;
description = "Individual elements of the indent markers";
default = {
corner = "└";
edge = "│";
Expand Down
2 changes: 1 addition & 1 deletion modules/statusline/lualine/lualine.nix
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ in {
default = "auto";
# TODO: xml generation error if the closing '' is on a new line.
# issue: https://gitlab.com/rycee/nmd/-/issues/10
defaultText = nvim.nmd.literalAsciiDoc ''`config.vim.theme.name` if theme supports lualine else "auto"'';
defaultText = ''`config.vim.theme.name` if theme supports lualine else "auto"'';
};

sectionSeparator = {
Expand Down
4 changes: 2 additions & 2 deletions modules/treesitter/context.nix
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ in {
};

trimScope = mkOption {
description = nvim.nmd.asciiDoc "Which context lines to discard if <<opt-vim.treesitter.context.maxLines>> is exceeded.";
description = "Which context lines to discard if [](#opt-vim.treesitter.context.maxLines) is exceeded.";
type = types.enum ["inner" "outer"];
default = "outer";
};
Expand All @@ -49,7 +49,7 @@ in {
};

separator = mkOption {
description = nvim.nmd.asciiDoc ''
description = ''
Separator between context and content. Should be a single character string, like '-'.
When separator is set, the context will only show up when there are at least 2 lines above cursorline.
Expand Down
2 changes: 1 addition & 1 deletion modules/treesitter/treesitter.nix
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ with lib; {
grammars = mkOption {
type = with types; listOf package;
default = [];
description = nvim.nmd.asciiDoc ''
description = ''
List of treesitter grammars to install. For supported languages
use the `vim.language.<lang>.treesitter` option
'';
Expand Down
1 change: 1 addition & 0 deletions modules/ui/breadcrumbs/breadcrumbs.nix
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,7 @@ in {
reorient = mkOption {
type = types.enum ["smart" "top" "mid" "none"];
default = "smart";
description = "reorient buffer after changing nodes";
};

scrolloff = mkOption {
Expand Down
6 changes: 3 additions & 3 deletions modules/visuals/visuals.nix
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,8 @@ in {
};

showEndOfLine = mkOption {
description = nvim.nmd.asciiDoc ''
Displays the end of line character set by <<opt-vim.visuals.indentBlankline.eolChar>> instead of the
description = ''
Displays the end of line character set by [](#opt-vim.visuals.indentBlankline.eolChar) instead of the
indent guide on line returns.
'';
type = types.bool;
Expand Down Expand Up @@ -110,7 +110,7 @@ in {
highlightForCount = mkOption {
type = types.bool;
default = true;
description = nvim.nmd.literalAsciiDoc ''
description = ''
Enable support for highlighting when a <count> is provided before the key
If set to false it will only highlight when the mapping is not prefixed with a <count>
'';
Expand Down

0 comments on commit 7bcfea2

Please sign in to comment.