diff --git a/Makefile b/Makefile index b002431..eddb26d 100644 --- a/Makefile +++ b/Makefile @@ -1,10 +1,10 @@ .PHONY: docs-serve docs-serve: - hugo -s docs serve + hugo -s docs/website serve .PHONY: docs-build docs-build: - hugo -s docs + hugo -s docs/website # Ideally, this should be done only in the remote CI environment with a certain # update cadence/rhythm. diff --git a/README.adoc b/README.adoc index 1043019..0b90a03 120000 --- a/README.adoc +++ b/README.adoc @@ -1 +1 @@ -docs/content/en/project-overview.adoc \ No newline at end of file +docs/website/content/en/project-overview.adoc \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore index 775b093..b83ab0b 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,22 +1,3 @@ -# All of the generated assets. -/content/*/nix-module-options/*/content.json - -### Hugo ### -# Generated files by hugo -/public/ -/resources/_gen/ -/assets/jsconfig.json -hugo_stats.json - -# Executable may be added to repository -hugo.exe -hugo.darwin -hugo.linux - -# Temporary lock file while building -/.hugo_build.lock - - ### Ruby ### *.gem *.rbc diff --git a/docs/README.adoc b/docs/README.adoc new file mode 100644 index 0000000..8e2c2e2 --- /dev/null +++ b/docs/README.adoc @@ -0,0 +1,11 @@ += Documentation +:toc: + +This is where the documentation is created, namely both the website and the manual page. + +* The website is powered by Hugo and it is pretty much what makes most of the files here. +It requires Hugo and whatever Hugo module feature requires so it isn't possible to build it offline. +For now, we rely on the remote CI having network access for it (which is pretty much the standard for the most part so no worries there). + +* The manual page is powered by some under-documented tool in the Nix ecosystem (as is tradition) called https://github.com/NixOS/nixpkgs/tree/de19b7eaffd1ec24c50a6a257f3674a841ab1221/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs[nixos-render-docs]. +The adjacent tools in the Nix-module-options-doc-generation ecosystem are also what makes the (autogenerated) Nix module options pages found in the website. diff --git a/docs/config/_default/menu.toml b/docs/config/_default/menu.toml deleted file mode 100644 index 69faaa7..0000000 --- a/docs/config/_default/menu.toml +++ /dev/null @@ -1,9 +0,0 @@ -[[main]] -identifier = "nix-module-options" -name = "Module options" -url = "nix-module-options/" - -[[main]] -identifier = "source-code" -name = "Source code" -url = "https://github.com/foo-dogsquared/wrapper-manager-fds" diff --git a/docs/default.nix b/docs/default.nix index bf3a287..fe66d43 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -11,74 +11,103 @@ in let inherit (pkgs) nixosOptionsDoc stdenv lib; + + # Pretty much inspired from home-manager's documentation build process. + evalDoc = args@{ modules, includeModuleSystemOptions ? false, ... }: + let + options = (pkgs.lib.evalModules { + modules = modules ++ [ { _module.check = false; } ]; + class = "wrapperManager"; + }).options; + in + nixosOptionsDoc ({ + options = + if includeModuleSystemOptions + then options + else builtins.removeAttrs options [ "_module" ]; + } + // builtins.removeAttrs args [ "modules" "includeModuleSystemOptions" ]); buildHugoSite = pkgs.callPackage ./hugo-build-module.nix { }; - wrapperManagerLib = import ../lib/env.nix; - wrapperManagerEval = wrapperManagerLib.eval { inherit pkgs; }; - - optionsDoc = nixosOptionsDoc { inherit (wrapperManagerEval) options; }; - - gems = pkgs.bundlerEnv { - name = "wrapper-manager-fds-gem-env"; - ruby = pkgs.ruby_3_1; - gemdir = ./.; + wmOptionsDoc = evalDoc { + modules = [ ../modules/wrapper-manager ]; + includeModuleSystemOptions = true; }; - - # Now this is some dogfooding. - asciidoctorWrapped = - wrapperManagerLib.build { - inherit pkgs; - modules = [ - ({ config, lib, pkgs, ... }: { - wrappers.asciidoctor = { - arg0 = lib.getExe' gems "asciidoctor"; - appendArgs = [ - "-T" "${sources.website}/templates" - ]; - }; - }) - ]; - }; in -buildHugoSite { - pname = "wrapper-manager-docs"; - version = "2024-07-13"; +{ + website = + let + gems = pkgs.bundlerEnv { + name = "wrapper-manager-fds-gem-env"; + ruby = pkgs.ruby_3_1; + gemdir = ./.; + }; - src = lib.fileset.toSource { - root = ./.; - fileset = lib.fileset.unions [ - ./assets - ./config - ./content - ./layouts - ./go.mod - ./go.sum - ]; - }; + wrapperManagerLib = (import ../. { }).lib; - vendorHash = "sha256-vMLi8of2eF/s60B/lM3FDfSntEyieGkvJbTSMuI7Wws="; + # Now this is some dogfooding. + asciidoctorWrapped = + wrapperManagerLib.build { + inherit pkgs; + modules = [ + ({ config, lib, pkgs, ... }: { + wrappers.asciidoctor = { + arg0 = lib.getExe' gems "asciidoctor"; + appendArgs = [ + "-T" "${sources.website}/templates" + ]; + }; + }) + ]; + }; + in + buildHugoSite { + pname = "wrapper-manager-docs"; + version = "2024-07-13"; - buildInputs = with pkgs; [ - asciidoctorWrapped - hugo - git - gems - gems.wrappedRuby - ]; + src = lib.fileset.toSource { + root = ./.; + fileset = lib.fileset.unions [ + ./website/assets + ./website/config + ./website/content + ./website/layouts + ./website/go.mod + ./website/go.sum + ]; + }; - installPhase = '' - runHook preInstall - cp --reflink=auto "$src/public" "$out" - runHook postInstall + vendorHash = "sha256-vMLi8of2eF/s60B/lM3FDfSntEyieGkvJbTSMuI7Wws="; + + buildInputs = with pkgs; [ + asciidoctorWrapped + hugo + git + gems + gems.wrappedRuby + ]; + + meta = with lib; { + description = "wrapper-manager-fds documentation"; + homepage = "https://github.com/foo-dogsquared/wrapper-manager-fds"; + license = with licenses; [ + mit + fdl13Only + ]; + platforms = platforms.all; + }; + }; + + inherit wmOptionsDoc; + wmNixosDoc = evalDoc { modules = [ ../modules/env/nixos ]; }; + wmHmDoc = evalDoc { modules = [ ../modules/env/home-manager ]; }; + + manualPage = pkgs.runCommand "wrapper-manager-reference-manpage" { + nativeBuildInputs = with pkgs; [ nixos-render-docs ]; + } '' + mkdir -p $out/share/man/man5 + nixos-render-docs options manpage \ + ${wmOptionsDoc.optionsJSON}/share/doc/nixos/options.json \ + $out/share/man/man5/wrapper-manager.nix.5 ''; - - meta = with lib; { - description = "wrapper-manager-fds documentation"; - homepage = "https://github.com/foo-dogsquared/wrapper-manager-fds"; - license = with licenses; [ - mit - fdl13Only - ]; - platforms = platforms.all; - }; } diff --git a/docs/shell.nix b/docs/shell.nix deleted file mode 100644 index 623927c..0000000 --- a/docs/shell.nix +++ /dev/null @@ -1,25 +0,0 @@ -let - sources = import ../npins; -in -{ pkgs ? import sources.nixos-unstable { } }: - -let - inherit (pkgs) nixosOptionsDoc; - websitePkg = import ./. { inherit pkgs; }; - wrapperManagerLib = import ../lib/env.nix; - - wrapperManagerEval = wrapperManagerLib.eval { inherit pkgs; }; - optionsDoc = nixosOptionsDoc { inherit (wrapperManagerEval) options; }; -in -with pkgs; mkShell { - inputsFrom = [ websitePkg ]; - - packages = [ - nodePackages.prettier - vscode-langservers-extracted - ]; - - shellHook = '' - install -Dm0644 ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./content/en-US/nix-module-options/module-environment/content.json - ''; -} diff --git a/docs/website/.gitignore b/docs/website/.gitignore new file mode 100644 index 0000000..fb0be8d --- /dev/null +++ b/docs/website/.gitignore @@ -0,0 +1,17 @@ +# All of the generated assets. +/content/**/wrapper-manager-*.adoc + +### Hugo ### +# Generated files by hugo +/public/ +/resources/_gen/ +/assets/jsconfig.json +hugo_stats.json + +# Executable may be added to repository +hugo.exe +hugo.darwin +hugo.linux + +# Temporary lock file while building +/.hugo_build.lock diff --git a/docs/assets/js/site.js b/docs/website/assets/js/site.js similarity index 100% rename from docs/assets/js/site.js rename to docs/website/assets/js/site.js diff --git a/docs/config/_default/config.toml b/docs/website/config/_default/config.toml similarity index 100% rename from docs/config/_default/config.toml rename to docs/website/config/_default/config.toml diff --git a/docs/config/_default/languages.toml b/docs/website/config/_default/languages.toml similarity index 100% rename from docs/config/_default/languages.toml rename to docs/website/config/_default/languages.toml diff --git a/docs/config/_default/markup.toml b/docs/website/config/_default/markup.toml similarity index 100% rename from docs/config/_default/markup.toml rename to docs/website/config/_default/markup.toml diff --git a/docs/website/config/_default/menu.toml b/docs/website/config/_default/menu.toml new file mode 100644 index 0000000..543c849 --- /dev/null +++ b/docs/website/config/_default/menu.toml @@ -0,0 +1,20 @@ +[[main]] +identifier = "nix-module-options" +name = "Module options" +url = "wrapper-manager-env-options/" +weight = 1 + +[[main]] +identifier = "source-code" +name = "Source code" +url = "https://github.com/foo-dogsquared/wrapper-manager-fds" + +[[main]] +identifier = "wrapper-manager-nixos" +name = "NixOS module" +url = "wrapper-manager-nixos-module/" + +[[main]] +identifier = "wrapper-manager-home-manager" +name = "home-manager module" +url = "wrapper-manager-home-manager-module/" diff --git a/docs/config/_default/module.toml b/docs/website/config/_default/module.toml similarity index 100% rename from docs/config/_default/module.toml rename to docs/website/config/_default/module.toml diff --git a/docs/content/en/project-overview.adoc b/docs/website/content/en/project-overview.adoc similarity index 100% rename from docs/content/en/project-overview.adoc rename to docs/website/content/en/project-overview.adoc diff --git a/docs/go.mod b/docs/website/go.mod similarity index 100% rename from docs/go.mod rename to docs/website/go.mod diff --git a/docs/go.sum b/docs/website/go.sum similarity index 100% rename from docs/go.sum rename to docs/website/go.sum diff --git a/docs/layouts/index.html b/docs/website/layouts/index.html similarity index 100% rename from docs/layouts/index.html rename to docs/website/layouts/index.html diff --git a/docs/website/shell.nix b/docs/website/shell.nix new file mode 100644 index 0000000..529b9a1 --- /dev/null +++ b/docs/website/shell.nix @@ -0,0 +1,22 @@ +let + sources = import ../../npins; +in +{ pkgs ? import sources.nixos-unstable { } }: + +let + docs = import ../. { inherit pkgs; }; +in +with pkgs; mkShell { + inputsFrom = [ docs.website ]; + + packages = [ + nodePackages.prettier + vscode-langservers-extracted + ]; + + shellHook = '' + install -Dm0644 ${docs.wmOptionsDoc.optionsAsciiDoc} ./content/en/wrapper-manager-env-options.adoc + install -Dm0644 ${docs.wmNixosDoc.optionsAsciiDoc} ./content/en/wrapper-manager-nixos-module.adoc + install -Dm0644 ${docs.wmHmDoc.optionsAsciiDoc} ./content/en/wrapper-manager-home-manager-module.adoc + ''; +}