Merge pull request #1538 from snoweuph/docs

docs: update ndg and fix linkcheck

.github/workflows/check.yml

@@ -127,7 +127,6 @@ jobs:
   flake-docs-linkcheck:
     name: "Validate hyperlinks in documentation sources"
     runs-on: ubuntu-latest
-    if: false # disabled until we fix ndg docs
     steps:
       - name: Checkout
         uses: actions/checkout@v6

docs/default.nix

@@ -92,7 +92,7 @@
 
   # Generate the HTML manual pages
   html = pkgs.callPackage ./manual.nix {
-    inherit inputs release;
+    inherit inputs;
     inherit (nvimModuleDocs) optionsJSON;
   };
 in {

docs/manual.nix

@@ -2,43 +2,57 @@
   inputs,
   path,
   stdenvNoCC,
-  runCommandLocal,
   optionsJSON,
-  release,
+  jaq,
 } @ args: let
   manual-release = args.release or "unstable";
 in
-  runCommandLocal "nvf-docs-html" {
+  stdenvNoCC.mkDerivation (finalAttrs: {
+    pname = "nvf-docs-html";
+    version = manual-release;
+    src = ./manual;
+
     nativeBuildInputs = [
-      (inputs.ndg.packages.${stdenvNoCC.system}.ndg.overrideAttrs
+      (inputs.ndg.packages.${stdenvNoCC.system}.ndg.overrideAttrs {
-        {
+        # FIXME: the tests take too long to build
-          # FIXME: the tests take too long to build
+        doCheck = false;
-          doCheck = false;
+      })
-        })
+      jaq
     ];
-  } ''
-    mkdir -p $out/share/doc
 
-    # Copy the markdown sources to be processed by ndg. This is not
+    patchPhase = ''
-    # strictly necessary, but allows us to modify the Markdown sources
+      # Replace variables following the @VARIABLE@ style in the manual
-    # as we see fit.
+      # pages. This can be built into ndg at a later date.
-    cp -rvf ${./manual} ./manual
+      substituteInPlace index.md \
+        --subst-var-by NVF_VERSION ${finalAttrs.version}
 
-    # Replace variables following the @VARIABLE@ style in the manual
+      language_options=$(cat "${optionsJSON}/share/doc/nixos/options.json" | jaq -r 'keys
-    # pages. This can be built into ndg at a later date.
+        | map(select(test("^vim\\.languages\\.[^.]+\\.enable$")))
-    substituteInPlace ./manual/index.md \
+        | map("- {option}`" + . + "`")
-      --subst-var-by NVF_VERSION ${manual-release}
+        | join("\n")'
+      )
 
-    # Generate the final manual from a set of parameters. This uses
+      substituteInPlace configuring/languages.md \
-    # feel-co/ndg to render the web manual.
+        --subst-var-by NVF_LANGUAGES_ENABLE "$language_options"
-    ndg --config-file ${./ndg.toml} html \
+    '';
-      --jobs $NIX_BUILD_CORES --title "NVF" \
-      --module-options ${optionsJSON}/share/doc/nixos/options.json \
-      --manpage-urls ${path}/doc/manpage-urls.json \
-      --input-dir ./manual \
-      --output-dir "$out/share/doc"
 
-    # Hydra support. Probably not necessary.
+    buildPhase = ''
-    mkdir -p $out/nix-support/
+      # Generate the final manual from a set of parameters. This uses
-    echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
+      # feel-co/ndg to render the web manual.
-  ''
+      ndg --config-file ${./ndg.toml} html \
+        --jobs $NIX_BUILD_CORES --title "NVF" \
+        --module-options ${optionsJSON}/share/doc/nixos/options.json \
+        --manpage-urls ${path}/doc/manpage-urls.json \
+        --input-dir . \
+        --output-dir build
+    '';
+
+    installPhase = ''
+      mkdir -p $out/share/doc
+      cp -r build/* $out/share/doc/
+
+      # Hydra support. Probably not necessary.
+      mkdir -p $out/nix-support/
+      echo "doc manual $out/share/doc index.html" >> $out/nix-support/hydra-build-products
+    '';
+  })

docs/manual/configuring/languages.md

@@ -6,85 +6,7 @@ formatters, and `nvim-lint` linter integration. This gets you capabilities
 ranging from autocompletion to formatting to diagnostics. The following
 languages have sections under the `vim.languages` attribute.
 
-- Rust:
+@NVF_LANGUAGES_ENABLE@
-  [vim.languages.rust.enable](./options.html#option-vim-languages-rust-enable)
-- Nix:
-  [vim.languages.nix.enable](./options.html#option-vim-languages-nix-enable)
-- SQL:
-  [vim.languages.sql.enable](./options.html#option-vim-languages-sql-enable)
-- C/C++:
-  [vim.languages.clang.enable](./options.html#option-vim-languages-clang-enable)
-- Typescript/Javascript:
-  [vim.languages.ts.enable](./options.html#option-vim-languages-ts-enable)
-- Python:
-  [vim.languages.python.enable](./options.html#option-vim-languages-python-enable):
-- Zig:
-  [vim.languages.zig.enable](./options.html#option-vim-languages-zig-enable)
-- Markdown:
-  [vim.languages.markdown.enable](./options.html#option-vim-languages-markdown-enable)
-- HTML:
-  [vim.languages.html.enable](./options.html#option-vim-languages-html-enable)
-- Dart:
-  [vim.languages.dart.enable](./options.html#option-vim-languages-dart-enable)
-- Go: [vim.languages.go.enable](./options.html#option-vim-languages-go-enable)
-- Lua:
-  [vim.languages.lua.enable](./options.html#option-vim-languages-lua-enable)
-- PHP:
-  [vim.languages.php.enable](./options.html#option-vim-languages-php-enable)
-- F#:
-  [vim.languages.fsharp.enable](./options.html#option-vim-languages-fsharp-enable)
-- Assembly:
-  [vim.languages.assembly.enable](./options.html#option-vim-languages-assembly-enable)
-- Astro:
-  [vim.languages.astro.enable](./options.html#option-vim-languages-astro-enable)
-- Bash:
-  [vim.languages.bash.enable](./options.html#option-vim-languages-bash-enable)
-- Clang:
-  [vim.languages.clang.enable](./options.html#option-vim-languages-clang-enable)
-- Clojure:
-  [vim.languages.clojure.enable](./options.html#option-vim-languages-clojure-enable)
-- C#:
-  [vim.languages.csharp.enable](./options.html#option-vim-languages-csharp-enable)
-- CSS:
-  [vim.languages.css.enable](./options.html#option-vim-languages-css-enable)
-- CUE:
-  [vim.languages.cue.enable](./options.html#option-vim-languages-cue-enable)
-- Elixir:
-  [vim.languages.elixir.enable](./options.html#option-vim-languages-elixir-enable)
-- Gleam:
-  [vim.languages.gleam.enable](./options.html#option-vim-languages-gleam-enable)
-- HCL:
-  [vim.languages.hcl.enable](./options.html#option-vim-languages-hcl-enable)
-- Helm:
-  [vim.languages.helm.enable](./options.html#option-vim-languages-helm-enable)
-- Julia:
-  [vim.languages.julia.enable](./options.html#option-vim-languages-julia-enable)
-- Kotlin:
-  [vim.languages.kotlin.enable](./options.html#option-vim-languages-kotlin-enable)
-- Nim:
-  [vim.languages.nim.enable](./options.html#option-vim-languages-nim-enable)
-- Nu: [vim.languages.nu.enable](./options.html#option-vim-languages-nu-enable)
-- OCaml:
-  [vim.languages.ocaml.enable](./options.html#option-vim-languages-ocaml-enable)
-- Odin:
-  [vim.languages.odin.enable](./options.html#option-vim-languages-odin-enable)
-- R: [vim.languages.r.enable](./options.html#option-vim-languages-r-enable)
-- Ruby:
-  [vim.languages.ruby.enable](./options.html#option-vim-languages-ruby-enable)
-- Scala:
-  [vim.languages.scala.enable](./options.html#option-vim-languages-scala-enable)
-- Svelte:
-  [vim.languages.svelte.enable](./options.html#option-vim-languages-svelte-enable)
-- Terraform:
-  [vim.languages.terraform.enable](./options.html#option-vim-languages-terraform-enable)
-- Typst:
-  [vim.languages.typst.enable](./options.html#option-vim-languages-typst-enable)
-- Vala:
-  [vim.languages.vala.enable](./options.html#option-vim-languages-vala-enable)
-- WGSL:
-  [vim.languages.wgsl.enable](./options.html#option-vim-languages-wgsl-enable)
-- YAML:
-  [vim.languages.yaml.enable](./options.html#option-vim-languages-yaml-enable)
 
 Adding support for more languages, and improving support for existing ones are
 great places where you can contribute with a PR.

docs/manual/hacking.md

@@ -717,7 +717,7 @@ require('lz.n').load({
 })
 ```
 
-[`vim.lazy.plugins` spec]: ./options.html#option-vim-lazy-plugins
+[`vim.lazy.plugins` spec]: ./options.html#option-vim.lazy.plugins
 
 A full list of options can be found in the [`vim.lazy.plugins` spec] on the
 rendered manual.
@@ -750,7 +750,7 @@ keybinding can look like this:
 }
 ```
 
-[module option documentation]: options.html#option-vim-keymaps
+[module option documentation]: options.html#option-vim.keymaps
 
 There are many other settings available in the keymap module. Please refer to
 the [module option documentation] for a full and up-to-date list of them.

docs/manual/installation/modules/home-manager.md

@@ -91,7 +91,7 @@ configure **nvf**.
 
 **nvf** exposes a lot of options, most of which are not referenced in the
 installation sections of the manual. You may find all available options in the
-[appendix](https://notashelf.github.io/nvf/options)
+[appendix](https://notashelf.github.io/nvf/options.html)
 
 :::
 

docs/manual/installation/modules/nixos.md

@@ -89,7 +89,7 @@ configure **nvf**.
 
 **nvf** exposes a lot of options, most of which are not referenced in the
 installation sections of the manual. You may find all available options in the
-[appendix](https://notashelf.github.io/nvf/options)
+[appendix](https://notashelf.github.io/nvf/options.html)
 
 :::
 

docs/manual/release-notes/rl-0.1.md

@@ -15,7 +15,7 @@ DAG implementation are from them.
   longer defined. If you use hare and would like it added back, please file an
   issue.
 
-- {option}`vim.startPlugins` & {option} `vim-optPlugins` are now an enum of
+- {option}`vim.startPlugins` & {option}`vim.optPlugins` are now an enum of
   `string` for options sourced from the flake inputs. Users can still provide
   vim plugin packages.
 

docs/manual/release-notes/rl-0.6.md

@@ -95,7 +95,7 @@ vim.api.nvim_set_keymap('n', '<leader>a', ':lua camelToSnake()<CR>', { noremap =
   and also has been removed.
 
 - `which-key.nvim` categories can now be customized through
-  [vim.binds.whichKey.register](./options.html#option-vim-binds-whichKey-register)
+  {option}`vim.binds.whichKey.register`
 
 - Added `magick` to `vim.luaPackages` for `image.nvim`.
 
@@ -125,10 +125,9 @@ vim.api.nvim_set_keymap('n', '<leader>a', ':lua camelToSnake()<CR>', { noremap =
 
 - Lualine module now allows customizing `always_divide_middle`, `ignore_focus`
   and `disabled_filetypes` through the new options:
-  [vim.statusline.lualine.alwaysDivideMiddle](./options.html#option-vim-statusline-lualine-alwaysDivideMiddle),
+  {option}`vim.statusline.lualine.alwaysDivideMiddle`,
-  [vim.statusline.lualine.ignoreFocus](./options.html#option-vim-statusline-lualine-ignoreFocus)
+  {option}`vim.statusline.lualine.ignoreFocus` and
-  and
+  {option}`vim.statusline.lualine.disabledFiletypes`).
-  [vim.statusline.lualine.disabledFiletypes](./options.html#option-vim-statusline-lualine-disabledFiletypes).
 
 - Updated all plugin inputs to their latest versions (**21.04.2024**) - this
   brought minor color changes to the Catppuccin theme.

docs/manual/release-notes/rl-0.8.md

@@ -85,7 +85,7 @@
 
 - Add [yazi.nvim] as a companion plugin for Yazi, the terminal file manager.
 
-- Add {option}`vim.autocmds` and {option}`vim-augroups` to allow declaring
+- Add {option}`vim.autocmds` and {option}`vim.augroups` to allow declaring
   autocommands via Nix.
 
 - Fix plugin `setupOpts` for yanky.nvim and assert if shada is configured as a

docs/manual/tips/plugin-sources.md

@@ -26,7 +26,7 @@ startup.
 }
 ```
 
-[`vim.extraPlugins`]: ./options.html#option-vim-extraPlugins
+[`vim.extraPlugins`]: ./options.html#option-vim.extraPlugins
 
 This will fetch aerial.nvim from nixpkgs, and add it to Neovim's runtime path to
 be loaded manually. Although for plugins that require manual setup, you are

flake.lock

@@ -58,11 +58,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1768214250,
+        "lastModified": 1776882296,
-        "narHash": "sha256-hnBZDQWUxJV3KbtvyGW5BKLO/fAwydrxm5WHCWMQTbw=",
+        "narHash": "sha256-DWZozXwMsgvUqfVlL1mQ8dOxW7GJ/8CdyaDN+1niZRg=",
         "owner": "feel-co",
         "repo": "ndg",
-        "rev": "a6bd3c1ce2668d096e4fdaaa03ad7f03ba1fbca8",
+        "rev": "ab7d78d4884b3a34968cf9fa3d16c0c1246d5c6e",
         "type": "github"
       },
       "original": {

flake/packages.nix

@@ -74,11 +74,16 @@
             inherit site;
 
             remap = {
-              "https://notashelf.github.io/nvf/" = site;
+              "https://notashelf.github.io/nvf/" = "${site}/share/doc/";
+              "https://nvf.notashelf.dev/" = "${site}/share/doc/";
             };
 
             extraConfig = {
-              exclude = [];
+              exclude = [
+                # This is not an email, but just part of an SCM query inside a nix code block.
+                # The leading escaped non breaking space is there on purpose.
+                "%C2%A0@injection.content"
+              ];
               include_mail = true;
               include_verbatim = true;
             };

modules/neovim/init/spellcheck.nix

@@ -30,7 +30,7 @@ in {
 
         To add your own language files, you may place your `spell` directory in either
         {file}`$XDG_CONFIG_HOME/nvf` or in a path that is included in the
-        [additionalRuntimePaths](./options.html#option-vim-additionalRuntimePaths) list provided by nvf.
+        {option}`vim.additionalRuntimePaths` list provided by nvf.
       '';
     };
 

modules/wrapper/rc/options.nix

@@ -284,7 +284,7 @@ in {
       default = "";
       defaultText = literalMD ''
         By default, this option will **append** paths in
-        {option}`vim-additionalRuntimePaths`
+        {option}`vim.additionalRuntimePaths`
         to the `runtimepath` and enable the experimental Lua module loader
         if {option}`vim.enableLuaLoader` is set to true.
       '';