From 07f23a60fdd0ea402bb0d0b6c4c9df89fa638c81 Mon Sep 17 00:00:00 2001 From: Matt Sturgeon Date: Wed, 20 Nov 2024 19:47:27 +0000 Subject: [PATCH] docs: link to all "available" versions of the docs --- .github/workflows/build_documentation.yml | 60 ++++++++++++++++++----- docs/mdbook/default.nix | 48 ++++++++++++++++++ docs/mdbook/index.md | 8 +++ 3 files changed, 104 insertions(+), 12 deletions(-) diff --git a/.github/workflows/build_documentation.yml b/.github/workflows/build_documentation.yml index 7d3cdca43e..f9625b251d 100644 --- a/.github/workflows/build_documentation.yml +++ b/.github/workflows/build_documentation.yml @@ -50,23 +50,54 @@ jobs: run: | set -ex + # A list of all doc versions to be built, + # (Written to versions.json) + echo ' + [ + { + "branch": "main", + "nixpkgsBranch": "nixos-unstable" + }, + { + "branch": "nixos-24.05", + "nixpkgsBranch": "nixos-24.05", + "subPath": "stable" + // TODO: consider having 24.05 instead of stable? + } + ] + ' | sed 's/^ *\/\/.*//' | jq \ + --arg repoName "$repoName" \ + 'map( + . + # Ensure subPath is a string + | .subPath = (.subPath // "") + # Construct baseHref from $repoName and .subPath + | .baseHref = ( + .subPath + | if . == "" then "" else "/\(.)" end + | $repoName + . + | "/\(.)/" + ) + )' > versions.json + # 1: branch - # 2: install dir (relative to /nixvim/) + # 2: baseHref + # 3: install dir build() { - branch="$1" - dir="${2:+/$2}" - flakeref="github:${repo}${branch:+/$branch}" - baseHref="/${repoName}${dir}/" - installDir="${out}${dir}" + flakeref="github:${repo}${1:+/$1}" + baseHref="$2" + installDir="${out}${3:+/$3}" - # Build docs for the given flake ref, overriding baseHref in the derivation args + # Build docs for the given flake ref, overriding the relevant derivation args nix build --impure \ --argstr flakeref "$flakeref" \ --argstr baseHref "$baseHref" \ + --arg-from-file versionsJson versions.json \ --expr ' { flakeref, baseHref, + versionsJson, system ? builtins.currentSystem, }: let @@ -75,6 +106,7 @@ jobs: in packages.docs.override { inherit baseHref; + availableVersions = builtins.fromJSON versionsJson; } ' @@ -83,12 +115,16 @@ jobs: cp -r result/share/doc/* "$installDir" } - # Install main-branch docs at the top-level - build 'main' '' + # For each version of the docs... + jq -c '.[]' versions.json | + while IFS=$"\n" read -r entry; do + branch=$(echo "$entry" | jq -r '.branch') + baseHref=$(echo "$entry" | jq -r '.baseHref') + installDir=$(echo "$entry" | jq -r '.subPath') - # Install 24.05 docs under 'stable' - # TODO: consider having `` instead of `stable` - build 'nixos-24.05' 'stable' + # Build this version of the docs + build "$branch" "$baseHref" "$installDir" + done - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/docs/mdbook/default.nix b/docs/mdbook/default.nix index 28d70b91ff..6d24aa4fef 100644 --- a/docs/mdbook/default.nix +++ b/docs/mdbook/default.nix @@ -1,5 +1,6 @@ { pkgs, + runCommand, lib, modules, helpers, @@ -8,6 +9,9 @@ hmOptions, # The root directory of the site baseHref ? "/", + # A list of all available docs that should be linked to + # Each element should contain { branch; nixpkgsBranch; baseHref; } + availableVersions ? [ ], }: with lib; let @@ -229,6 +233,46 @@ let ) docs.modules; }; + # Zip the list of attrs into an attr of lists, for use as bash arrays + zippedVersions = + assert lib.assertMsg + (lib.all (o: o ? branch && o ? nixpkgsBranch && o ? baseHref) availableVersions) + '' + Expected all "availableVersions" docs entries to contain { branch, nixpkgsBranch, baseHref } attrs! + ''; + lib.zipAttrs availableVersions; + + docs-versions = + runCommand "docs-versions" + { + __structuredAttrs = true; + branches = zippedVersions.branch or [ ]; + nixpkgsBranches = zippedVersions.nixpkgsBranch or [ ]; + baseHrefs = zippedVersions.baseHref or [ ]; + current = baseHref; + } + '' + touch "$out" + for i in ''${!branches[@]}; do + branch="''${branches[i]}" + nixpkgs="''${nixpkgsBranches[i]}" + baseHref="''${baseHrefs[i]}" + linkText="\`$branch\` branch" + + link= + suffix= + if [ "$baseHref" = "$current" ]; then + # Don't bother linking to ourselves + link="$linkText" + suffix=" _(this page)_" + else + link="[$linkText]($baseHref)" + fi + + echo "- The $link, for use with nixpkgs \`$nixpkgs\`$suffix" >> "$out" + done + ''; + prepareMD = '' # Copy inputs into the build directory cp -r --no-preserve=all $inputs/* ./ @@ -249,6 +293,10 @@ let substituteInPlace ./SUMMARY.md \ --replace-fail "@NIXVIM_OPTIONS@" "$(cat ${pkgs.writeText "nixvim-options-summary.md" mdbook.nixvimOptions})" + # Patch index.md + substituteInPlace ./index.md \ + --replace-fail "@DOCS_VERSIONS@" "$(cat ${docs-versions})" + substituteInPlace ./modules/hm.md \ --replace-fail "@HM_OPTIONS@" "$(cat ${mkMDDoc hmOptions})" ''; diff --git a/docs/mdbook/index.md b/docs/mdbook/index.md index 458477009e..d42fa5f7cc 100644 --- a/docs/mdbook/index.md +++ b/docs/mdbook/index.md @@ -1,5 +1,13 @@ # NixVim - A Neovim configuration system for nix +## Other versions of these docs + +Please ensure you are referencing documentation that corresponds to the Nixvim version you are using! + +Documentation is currently available for the following versions: + +@DOCS_VERSIONS@ + ## What is it? NixVim is a [Neovim](https://neovim.io) distribution built around [Nix](https://nixos.org) modules. It is distributed as a Nix flake, and