mirror/nix-community.nixvim
1
0
Fork 0
mirror of https://github.com/nix-community/nixvim.git synced 2025-06-21 00:25:42 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: New documentation using mdbook (#471)

Browse source 
* docs: mdbook init

* Separate sub-options into their section

* docs: enable fold

* docs: merge core options into a single section

* doc generation: fix submodules index pages

* docs: add contributing section

* docs: rename 'core' group to 'Neovim Options'

docs: removed the index pages of empty sections

docs: remove obsolete 'mergeFunctionResults' function

* docs: use nix syntax highlighting

* docs: point to the new repo url

* docs: use recursive generation
docs: split submodules into subsections

* docs: fix contributing separator
docs: fix missing submodules docs
This commit is contained in:
Wolbyte 2023-08-07 13:18:01 +03:30 • committed by GitHub
parent 718512f098
commit ecd593386f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
21 changed files with 301 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs.nix
View file

@ -1,39 +0,0 @@
{
pkgs,
lib,
modules,
...
}: let
options = lib.evalModules {
inherit modules;
specialArgs = {inherit pkgs lib;};
};
docs = pkgs.nixosOptionsDoc {
# If we don't do this, we end up with _module.args on the generated options, which we do not want
options = lib.filterAttrs (k: _: k != "_module") options.options;
warningsAreErrors = false;
};
asciidoc = docs.optionsAsciiDoc;
in
pkgs.stdenv.mkDerivation {
name = "nixvim-docs";
src = asciidoc;
buildInputs = [
pkgs.asciidoctor
];
phases = ["buildPhase"];
buildPhase = ''
mkdir -p $out/share/doc
cat <<EOF > header.adoc
= NixVim options
This lists all the options available for NixVim.
:toc:
EOF
cat header.adoc $src > tmp.adoc
asciidoctor tmp.adoc -o $out/share/doc/index.html
'';
}

11
docs/SUMMARY.md Normal file
View file

@ -0,0 +1,11 @@
# Structure for nixvim docs
# Options
@NIXVIM_OPTIONS@
#
---
[Contributing](./CONTRIBUTING.md)

10
docs/book.toml Normal file
View file

@ -0,0 +1,10 @@
[book]
authors = []
language = "en"
multilingual = false
src = "."
title = "nixvim docs"
[output.html.fold]
enable = true
level = 0

235
docs/default.nix Normal file
View file

@ -0,0 +1,235 @@
{
pkgs,
lib,
modules,
...
}:
with lib; let
options = lib.evalModules {
inherit modules;
specialArgs = {inherit pkgs lib;};
};
mkMDDoc = options:
(pkgs.nixosOptionsDoc {
options = filterAttrs (k: _: k != "_module") options;
warningsAreErrors = false;
transformOptions = opts:
opts
// {
declarations = with builtins;
map
(
decl:
if hasPrefix "/nix/store/" decl
then let
filepath = toString (match "^/nix/store/[^/]*/(.*)" decl);
in {
url = "https://github.com/nix-community/nixvim/blob/main/${filepath}";
name = filepath;
}
else decl
)
opts.declarations;
};
})
.optionsCommonMark;
removeUnwanted = attrs:
builtins.removeAttrs attrs [
"_module"
"_freeformOptions"
"warnings"
"assertions"
"content"
];
removeWhitespace = builtins.replaceStrings [" "] [""];
getSubOptions = opts: path: removeUnwanted (opts.type.getSubOptions path);
wrapModule = path: opts: isOpt: rec {
index = {
options =
if isOpt
then opts
else filterAttrs (_: component: component.isOption) opts;
path = concatStringsSep "/" path;
};
components =
if isOpt
then {}
else filterAttrs (_: component: !component.isOption) opts;
hasComponents = components != {};
isOption = isOpt;
};
processModulesRec = modules: let
recurse = path: mods: let
g = name: opts:
if !isOption opts
then wrapModule (path ++ [name]) (recurse (path ++ [name]) opts) false
else let
subOpts = getSubOptions opts (path ++ [name]);
in
if subOpts != {}
then
wrapModule
(path ++ [name])
(
(recurse (path ++ [name]) subOpts)
// {
# This is necessary to include the submodule option's definition in the docs (description, type, etc.)
# For instance, this helps submodules like "autoCmd" to include their base definitions and examples in the docs
# Though there might be a better, less "hacky" solution than this.
${name} = recursiveUpdate opts {
isOption = true;
type.getSubOptions = _: _: {}; # Used to exclude suboptions from the submodule definition itself
};
}
)
false
else wrapModule (path ++ [name]) opts true;
in
mapAttrs g mods;
in
foldlAttrs
(
acc: name: opts: let
group =
if !opts.hasComponents
then "Neovim Options"
else "none";
last =
acc.${group}
or {
index = {
options = {};
path = removeWhitespace "${group}";
};
components = {};
isGroup = true;
hasComponents = false;
};
isOpt = !opts.hasComponents && (isOption opts.index.options);
in
acc
// {
${group} = recursiveUpdate last {
index.options = optionalAttrs isOpt {
${name} = opts.index.options;
};
components = optionalAttrs (!isOpt) {
${name} = recursiveUpdate opts {
index.path = removeWhitespace (concatStringsSep "/" ((optional (group != "none") group) ++ [opts.index.path]));
hasComponents = true;
};
};
hasComponents = last.components != {};
};
}
)
{}
(recurse [] modules);
mapModulesToString = f: modules: let
recurse = mods: let
g = name: opts:
if (opts ? "isGroup")
then
if name != "none"
then (f name opts) + ("\n" + recurse opts.components)
else recurse opts.components
else if opts.hasComponents
then (f name opts) + ("\n" + recurse opts.components)
else f name opts;
in
concatStringsSep "\n" (mapAttrsToList g mods);
in
recurse modules;
docs = rec {
modules = processModulesRec (removeUnwanted options.options);
commands =
mapModulesToString
(
name: opts: let
isBranch =
if (hasSuffix "index" opts.index.path)
then true
else opts.hasComponents;
path =
if isBranch
then "${opts.index.path}/index.md"
else "${opts.index.path}.md";
in
(optionalString isBranch
"mkdir -p ${opts.index.path}\n")
+ "cp ${mkMDDoc opts.index.options} ${path}"
)
modules;
};
mdbook = {
nixvimOptions =
mapModulesToString
(
name: opts: let
isBranch =
if name == "index"
then true
else opts.hasComponents && opts.index.options != {};
path =
if isBranch
then "${opts.index.path}/index.md"
else if !opts.hasComponents
then "${opts.index.path}.md"
else "";
indentLevel = with builtins; length (filter isString (split "/" opts.index.path)) - 1;
padding = concatStrings (builtins.genList (_: "\t") indentLevel);
in "${padding}- [${name}](${path})"
)
docs.modules;
};
prepareMD = ''
# Copy inputs into the build directory
cp -r --no-preserve=all $inputs/* ./
cp ${../CONTRIBUTING.md} ./CONTRIBUTING.md
# Copy the generated MD docs into the build directory
# Using pkgs.writeShellScript helps to avoid the "bash: argument list too long" error
${pkgs.writeShellScript "copy_docs" docs.commands}
# Prepare SUMMARY.md for mdBook
# Using pkgs.writeText helps to avoid the same error as above
substituteInPlace ./SUMMARY.md \
--replace "@NIXVIM_OPTIONS@" "$(cat ${pkgs.writeText "nixvim-options-summary.md" mdbook.nixvimOptions})"
'';
in
pkgs.stdenv.mkDerivation {
name = "nixvim-docs";
phases = ["buildPhase"];
buildInputs = [pkgs.mdbook];
inputs = sourceFilesBySuffices ./. [".md" ".toml" ".js"];
buildPhase = ''
dest=$out/share/doc
mkdir -p $dest
${prepareMD}
mdbook build
cp -r ./book/* $dest
'';
}

6
docs/highlight.js Normal file
View file

File diff suppressed because one or more lines are too long

2
flake.nix
View file

@ -117,7 +117,7 @@
};
};
packages = {
docs = pkgs-unfree.callPackage (import ./docs.nix) {
docs = pkgs-unfree.callPackage (import ./docs) {
modules = nixvimModules;
};
runUpdates =

4
plugins/colorschemes/kanagawa.nix
View file

@ -76,7 +76,7 @@ in {
Change specific usages for a certain theme, or for all of them
Example:
```
```nix
{
wave = {
ui = {
@ -103,7 +103,7 @@ in {
Change all usages of these colors.
Example:
```
```nix
{
sumiInk0 = "#000000";
fujiWhite = "#FFFFFF";

6
plugins/completion/copilot-lua.nix
View file

@ -89,7 +89,7 @@ in {
Each value can be either a boolean or a lua function that returns a boolean.
Example:
```
```nix
{
markdown = true; # overrides default
terraform = false; # disallow specific filetype
@ -107,7 +107,7 @@ in {
The key `"*"` can be used to disable the default configuration.
Example:
```
```nix
{
javascript = true; # allow specific filetype
typescript = true; # allow specific filetype
@ -138,7 +138,7 @@ in {
See `:h vim.lsp.start_client` for list of options.
Example:
```
```nix
{
trace = "verbose";
settings = {

2
plugins/completion/nvim-cmp/default.nix
View file

@ -126,7 +126,7 @@ in {
- ultisnips
You can also provide a custom function:
```
```nix
{
__raw = \'\'
function(args)

2
plugins/dap/dap-ui.nix
View file

@ -122,7 +122,7 @@ in {
layouts =
helpers.defaultNullOpts.mkNullable (types.listOf layoutOption)
''
```
```nix
[
{
elements = [

10
plugins/filetrees/neo-tree.nix
View file

@ -317,7 +317,7 @@ in {
- values are lua code defining the callback function.
Example:
```
```nix
{
before_render = \'\'
function (state)
@ -626,7 +626,7 @@ in {
mappings =
mkMappingsOption
''
```
```nix
{
"<space>" = {
command = "toggle_node";
@ -679,7 +679,7 @@ in {
};
filesystem = helpers.mkCompositeOption "Filesystem options" {
window = mkWindowMappingsOption (lib.mdDoc ''
```
```nix
{
H = "toggle_hidden";
"/" = "fuzzy_finder";
@ -747,7 +747,7 @@ in {
Hide by pattern.
Example:
```
```nix
[
"*.meta"
"*/src/*/tsconfig.json"
@ -808,7 +808,7 @@ in {
Either use a list of strings:
```
```nix
findArgs = {
fd = [
"--exclude"

4
plugins/languages/nvim-jdtls.nix
View file

@ -21,7 +21,7 @@ in {
You should either set a value for this option, or, you can instead set the `data` (and
`configuration`) options.
```
```nix
plugins.nvim-jdtls = {
enable = true;
cmd = [
@ -34,7 +34,7 @@ in {
```
Or,
```
```nix
plugins.nvim-jdtls = {
enable = true;
data = "/path/to/your/workspace";

2
plugins/languages/sniprun.nix
View file

@ -36,7 +36,7 @@ in {
only sucessful runs (or errored-out runs respectively)
Example:
```
```nix
[
"Classic" # display results in the command-line area
"VirtualTextOk" # display ok results as virtual text (multiline is shortened)

4
plugins/languages/vim-slime.nix
View file

@ -53,14 +53,14 @@ in
Examples:
- `tmux`:
```
```nix
{
socket_name = "default";
target_pane = "{last}";
}
```
- `zellij`:
```
```nix
{
session_id = "current";
relative_pane = "right";

24
plugins/lsp/language-servers/ltex-settings.nix
View file

@ -100,7 +100,7 @@ in {
''
Lists of additional words that should not be counted as spelling errors.
This setting is language-specific, so use an attrs of the format
```
```nix
{
"<LANGUAGE1>" = [
"<WORD1>"
@ -121,7 +121,7 @@ in {
By default, no additional spelling errors will be ignored.
Example:
```
```nix
{
"en-US" = [
"adaptivity"
@ -143,7 +143,7 @@ in {
''
Lists of rules that should be disabled (if enabled by default by LanguageTool).
This setting is language-specific, so use an attrs of the format
```
```nix
{
"<LANGUAGE1>" = [
"<WORD1>"
@ -165,7 +165,7 @@ in {
By default, no additional rules will be disabled.
Example:
```
```nix
{
"en-US" = [
"EN_QUOTES"
@ -183,7 +183,7 @@ in {
''
Lists of rules that should be enabled (if disabled by default by LanguageTool).
This setting is language-specific, so use an attrs of the format
```
```nix
{
"<LANGUAGE1>" = [
"<WORD1>"
@ -205,7 +205,7 @@ in {
By default, no additional rules will be enabled.
Example:
```
```nix
{
"en-GB" = [
"PASSIVE_VOICE"
@ -224,7 +224,7 @@ in {
Lists of false-positive diagnostics to hide (by hiding all diagnostics of a specific rule
within a specific sentence).
This setting is language-specific, so use an attrs of the format
```
```nix
{
"<LANGUAGE1>" = [
"<JSON1>"
@ -256,7 +256,7 @@ in {
If this list is very large, performance may suffer.
Example:
```
```nix
{
"en-US" = [ ":/path/to/externalFile.txt" ];
}
@ -273,7 +273,7 @@ in {
Some common fields are already ignored, even if you set this setting to an empty attrs.
Example:
```
```nix
{
maintitle = false;
seealso = true;
@ -295,7 +295,7 @@ in {
attrs.
Example:
```
```nix
{
"\\label{}" = "ignore";
"\\documentclass[]{}" = "ignore";
@ -315,7 +315,7 @@ in {
attrs.
Example:
```
```nix
{
lstlisting = "ignore";
verbatim = "ignore";
@ -338,7 +338,7 @@ in {
empty attrs.
Example:
```
```nix
{
CodeBlock = "ignore";
FencedCodeBlock = "ignore";

2
plugins/utils/coverage.nix
View file

@ -244,7 +244,7 @@ in {
See plugin documentation for language specific options.
Example:
```
```nix
{
python = {
coverage_file = ".coverage";

2
plugins/utils/leap.nix
View file

@ -60,7 +60,7 @@ in {
either be defined as strings or tables.
Example:
```
```nix
[
"\r\n"
")]}>"

2
plugins/utils/neogen.nix
View file

@ -93,7 +93,7 @@ in {
https://github.com/danymat/neogen/blob/main/docs/adding-languages.md#default-generator
Example:
```
```nix
{
csharp = {
template = {

2
plugins/utils/presence-nvim.nix
View file

@ -84,7 +84,7 @@ in {
`source`: The source of the asset, either an art asset key or the URL of an image asset.
Example:
```
```nix
{
# Use art assets uploaded in Discord application for the configured client id
js = [ "JavaScript" "javascript" ];

6
plugins/utils/todo-comments.nix
View file

@ -55,7 +55,7 @@ in {
Configurations for keywords to be recognized as todo comments.
Default:
```
```nix
{
FIX = {
icon = " "; # Icon used for the sign, and in search results.
@ -144,7 +144,7 @@ in {
of highlight groups or use the hex color if hl not found as a fallback.
Default:
```
```nix
{
error = [ "DiagnosticError" "ErrorMsg" "#DC2626" ];
warning = [ "DiagnosticWarn" "WarningMsg" "#FBBF24" ];
@ -163,7 +163,7 @@ in {
Arguments to use for the search command in list form.
Default:
```
```nix
[
"--color=never"
"--no-heading"

4
plugins/utils/toggleterm.nix
View file

@ -19,7 +19,7 @@ in {
Size of the terminal.
`size` can be a number or function
Example:
```
```nix
size = 20
```
OR
@ -78,7 +78,7 @@ in {
Highlights which map to a highlight group name and a table of it's values.
Example:
```
```nix
highlights = {
Normal = {
guibg = "<VALUE-HERE>";