doc: init by ju1m · Pull Request #1891 · ngi-nix/ngipkgs

ju1m · 2025-12-08T18:49:19Z

This PR introduces a demo of what could be used to make documentation for NGIpkgs, currently three documents:

NGIpkgs User Manual
NGIpkgs Contributor Manual
NGIpkgs Options, generated from documentation bits in modules.

State

Based upon:

The tooling used by https://nix.dev:
- MyST;
- sphinx.
Custom MyST rendition of programs and services options from optionsNix.

Build and read with:

$ nix -L build -f . manuals.singlehtml
$ xdg-open result/index.html

$ nix -L build -f . manuals.html
$ xdg-open result/index.html

$ nix -L build -f . manuals.latexpdf
$ xdg-open result/NGIpkgs_*.pdf

$ nix -L build -f . manuals.man
$ man ./result/share/man/man5/*.5.gz

$ nix -L build -f . manuals.info
$ pinfo ./result/share/info/*.info

RoadMap

Host the HTML rendition somewhere online.

imincik

@ju1m , thanks for this PR. I am getting the principals of Diataxis now and it makes a sense for me. I think we can make a use of it. I'll create a user story for it.

imincik · 2025-12-11T08:22:26Z

User story created: #1893

eljamm

I've only had a brief look at the manual entrypoint and will have a more in-depth one once these comments have been addressed and I can build it locally.

eljamm

There are probably more things to address, but let's go through this step by step. I've included a patch for most of the things I reviewed for convenience:

0001-Review-suggestions.patch

From ac9e7ca0a18acade0b93b1dfed4b81743ca50248 Mon Sep 17 00:00:00 2001
From: eljamm <fedi.jamoussi@protonmail.ch>
Date: Thu, 8 Jan 2026 10:13:30 +0100
Subject: [PATCH] Review suggestions

---
 default.nix                    |   3 +-
 maintainers/shells/default.nix |  11 +++
 manuals/default.nix            | 125 +++++++++------------------------
 3 files changed, 45 insertions(+), 94 deletions(-)

diff --git a/default.nix b/default.nix
index 6dc3ac13..a52a8990 100644
--- a/default.nix
+++ b/default.nix
@@ -57,10 +57,9 @@ let
       options = self.optionsDoc.optionsNix;
     };
 
-    manuals = pkgs.callPackage manuals/default.nix rec {
+    manuals = self.call manuals/default.nix rec {
       version = "0.0.0"; # FixMe(maint): use something better, alas self.rev is not available there.
       revision = "release-${version}";
-      inherit (self.project-utils.raw-projects.config) projects;
       modulesPath = "${sources.nixpkgs}/nixos/modules";
     };
 
diff --git a/maintainers/shells/default.nix b/maintainers/shells/default.nix
index 0fc85b65..c88fc682 100644
--- a/maintainers/shells/default.nix
+++ b/maintainers/shells/default.nix
@@ -12,6 +12,17 @@ pkgs.mkShellNoCC {
       buildArgs = "-A overview --show-trace -v";
     })
 
+    (pkgs.writeShellApplication {
+      name = "devmode-manual";
+      text = ''
+        ${lib.getExe (
+          pkgs.devmode.override {
+            buildArgs = "-A manuals --show-trace -v";
+          }
+        )}
+      '';
+    })
+
     (pkgs.writeShellApplication {
       # TODO: have the program list available tests
       name = "ngipkgs-test";
diff --git a/manuals/default.nix b/manuals/default.nix
index 928835aa..67092afd 100644
--- a/manuals/default.nix
+++ b/manuals/default.nix
@@ -1,78 +1,20 @@
 {
-  callPackage,
   lib,
+  callPackage,
+  nixosOptionsDoc,
+  perl,
   python3,
   stdenv,
   texlive,
-  version,
-  projects,
-  nixosOptionsDoc,
+
   modulesPath,
-  pkgs,
+  nixos-modules,
+  version,
   ...
 }:
-let
-  pythonPackages = python3.withPackages (
-    pyPkgs: with pyPkgs; [
-      linkify-it-py
-      myst-parser
-      sphinx
-      #sphinx-argparse
-      #sphinx-autoapi
-      #sphinx-autobuild
-      #sphinx-autodoc-typehints
-      #sphinx-autodoc2
-      #sphinx-automodapi
-      #sphinx-basic-ng
-      #sphinx-better-theme
-      sphinx-book-theme
-      #sphinx-click
-      #sphinx-codeautolink
-      #sphinx-comments
-      sphinx-copybutton
-      sphinx-design
-      #sphinx-external-toc
-      #sphinx-favicon
-      #sphinx-fortran
-      #sphinx-hoverxref
-      #sphinx-inline-tabs
-      #sphinx-intl
-      #sphinx-issues
-      #sphinx-jinja
-      #sphinx-jinja2-compat
-      #sphinx-jquery
-      #sphinx-jupyterbook-latex
-      #sphinx-last-updated-by-git
-      #sphinx-lv2-theme
-      #sphinx-markdown-builder
-      #sphinx-markdown-parser
-      #sphinx-markdown-tables
-      #sphinx-material
-      #sphinx-mdinclude
-      #sphinx-multitoc-numbering
-      #sphinx-multiversion
-      sphinx-notfound-page
-      #sphinx-prompt
-      #sphinx-pytest
-      #sphinx-remove-toctrees
-      #sphinx-reredirects
-      #sphinx-rtd-dark-mode
-      #sphinx-rtd-theme
-      #sphinx-serve
-      sphinx-sitemap
-      #sphinx-tabs
-      #sphinx-testing
-      #sphinx-thebe
-      #sphinx-tippy
-      #sphinx-togglebutton
-      #sphinx-toolbox
-      #sphinx-version-warning
-      #sphinx-versions
-    ]
-  );
-in
-stdenv.mkDerivation {
+stdenv.mkDerivation (finalAttrs: {
   name = "NGIpkgs-Manuals";
+  inherit version;
   src =
     with lib.fileset;
     toSource {
@@ -98,14 +40,9 @@ stdenv.mkDerivation {
       ];
     };
   nativeBuildInputs = [
-    pythonPackages
-    pkgs.perl
-    # Explanation: generated with nix run github:rgri/tex2nix -- *.tex *.sty
-    (callPackage ./tex-env.nix {
-      extraTexPackages = {
-        inherit (texlive) latexmk gnu-freefont;
-      };
-    })
+    finalAttrs.passthru.pythonPackages
+    finalAttrs.passthru.texEnv
+    perl
   ];
   patchPhase = ''
     substituteInPlace manuals/index.md \
@@ -127,34 +64,38 @@ stdenv.mkDerivation {
     popd
   '';
   passthru = {
+    pythonPackages = python3.withPackages (
+      pyPkgs: with pyPkgs; [
+        linkify-it-py
+        myst-parser
+        sphinx
+        sphinx-book-theme
+        sphinx-copybutton
+        sphinx-design
+        sphinx-notfound-page
+        sphinx-sitemap
+      ]
+    );
+    # generated with: nix run github:rgri/tex2nix -- *.tex *.sty
+    texEnv = callPackage ./tex-env.nix {
+      extraTexPackages = {
+        inherit (texlive) latexmk gnu-freefont;
+      };
+    };
     optionsDoc = nixosOptionsDoc {
       options =
         lib.flip builtins.removeAttrs [ "_module" ]
           (lib.evalModules {
             class = "nixos";
-            specialArgs = {
-              inherit pkgs modulesPath;
-            };
+            specialArgs = { inherit modulesPath; };
             modules = [
               {
                 config = {
-                  # Explanation: do not check anything
-                  # because NixOS options are not included.
+                  # Do not check anything because NixOS options are not included.
                   # See also comment in NixOS' `noCheckForDocsModule`.
                   _module.check = false;
                 };
-                imports = lib.flatten (
-                  lib.attrValues (
-                    lib.mapAttrs (
-                      name: project:
-                      lib.attrValues (
-                        lib.filterAttrs (_: module: module != null) (
-                          lib.mapAttrs (n: p: p.module or null) (project.nixos.modules.services or { })
-                        )
-                      )
-                    ) projects
-                  )
-                );
+                imports = lib.attrValues nixos-modules.services;
                 #options = (import projects/types.nix { inherit lib; }).options;
                 #inherit (self.project-utils.eval-projects) options;
               }
@@ -162,4 +103,4 @@ stdenv.mkDerivation {
           }).options;
     };
   };
-}
+})
-- 
2.51.2

eljamm · 2026-01-08T09:12:42Z

We could add a manuals devmode to shells/default.nix:

(pkgs.writeShellApplication { name = "devmode-manuals"; text = '' ${lib.getExe ( pkgs.devmode.override { buildArgs = "-A manuals --show-trace -v"; } )} ''; })

If we're introducing more dev tools I think #1880 (comment) is needed more than ever.

imincik · 2026-01-12T10:47:29Z

@ju1m , is it possible to split this PR to multiple smaller ones ? It is very hard to review or approve 180 files.

First PR could only contain working, but empty documentation structure - just working implementation of documentation framework
Next we can integrate it to our GitHub pages website
After that we can start merging some real content

ju1m · 2026-01-13T07:55:39Z

Rebase after underlying PR build(doc): fix various things preventing to generate optionsDoc for services and programs. #1942 has been merged

eljamm · 2026-01-13T07:29:08Z

+    manuals = self.call manuals/default.nix rec {
+      version = "0.0.0"; # FixMe(maint): use something better, alas self.rev is not available there.
+      revision = "release-${version}";
+      inherit (self.project-utils.raw-projects.config) projects;


Not used

Suggested change

inherit (self.project-utils.raw-projects.config) projects;

eljamm · 2026-01-13T07:30:23Z


+    manuals = self.call manuals/default.nix rec {
+      version = "0.0.0"; # FixMe(maint): use something better, alas self.rev is not available there.
+      revision = "release-${version}";


This doesn't seem to be used in manuals/default.nix

eljamm · 2026-01-13T07:33:36Z

+                # Explanation: do not check anything
+                # because NixOS options are not included.
+                # See also comment in NixOS' `noCheckForDocsModule`.
+                _module.check = false;


I've been meaning to ask, why do you always append Explanation: to comments? I think it's a bit redundant since their purpose is to explain things, in the first place.

I gave you my rationale there
They are all kind of comments, not all of them explain things, so I classify them to ease their digesting, facilitate their browsing and keeping their content in focus.
The current taxonomy is not perfect, always up for discussion, I hope you can agree with me, but of course you have the final word.

I gave you my rationale there

Oh, I didn't notice.

They are all kind of comments, not all of them explain things, so I classify them to ease their digesting, facilitate their browsing and keeping their content in focus.

I don't know about other contributors, but personally I find Explanation: a bit distracting, especially since comments are meant to document and explain things by default. To me, it doesn't make much sense to be explicit like that in situations where this is self-implied.

Explanation: is a classification header that I consider as important as ToDo:, Warning:, Issue: , FixMe:, Description:, Documentation:.

This is surely up to preference, but the TODO-comments are usually short (FIX, WARN, NOTE, ...) that it's not so distracting for me, whereas the length and capitalization in these stick out too much, IMO.

comments are meant to document and explain things by default.

I browsed the comments and you're perfectly right that most untagged comments
in packages and services are explanations (answering "why?")
with some exceptions here and there which are rather:

descriptions,

history
notes,

alternative
implementations

invariant to respect.

mix of different concerns

section titles

As an aside, in libraries (eg. pkgs/lib.nix or overview.utils)
untagged comments are most often descriptions (answering "what?").

Now, since having this classifier does not have the expected effect of helping you
to parse/browse/check-existence-of explaining comments,
I'll fallback to untagged comments for explanations.

For the record, it's because explanations are dignified
with their own separate category in https://diataxis.fr
that I logically introduced this new classifier
(sometimes tagged further down with a scope between parenthesis),
to nudge me to actually explain things, instead of not writing any explaination,
or just describing what the code already states.

eljamm · 2026-01-13T07:57:45Z

+    writeText "options.md" (
+      ''
+        {#User_What_is_the_tree_of_options}
+        # What is the tree of options?
+
+        The following tree of options is provided by importing:
+        - `inputs.NGIpkgs.nixosModules.programs`
+        - `inputs.NGIpkgs.nixosModules.services`
+


Do we want/need the list of options when we already this in the overview? The biggest disadvantage to me for this approach is that the list is too long and encumbered, making it difficult to read.

I think it would be better to split this into a separate PR where we can discuss how we should present this without blocking this PR, since options aren't really essential for the manual. And ideally, we should have a user story to state what the manual is accomplishing and what value it adds to users.

What do you think @imincik?

Where is the list of options in the overview?
Note that it could not have been generated without the fixes from #1942
The options' sections are hidden from the ToC, still available in the document ToC in a PDF viewer's side-window.
Funny, for me options are like the most essential thing I'm expecting from a User manual.
Anyway, I'll split in another PR.

List of options in ngipkgs might not be that relevant as for example in nixpkgs. Our users will find available options listed in project instructions in ngi.nixos.org and we don't expect them to configure multiple projects at once.

But I am ok with having the list options in manual if they don't flood content.

@ju1m , I just built the manual and I definitely don't think we should have configuration options listed on the home page as I see it now. Are you able to move them to separate (Configuration options) page ? Thanks.

imincik · 2026-01-19T08:55:21Z

+    writeText "options.md" (
+      ''
+        {#User_What_is_the_tree_of_options}
+        # What is the tree of options?
+
+        The following tree of options is provided by importing:
+        - `inputs.NGIpkgs.nixosModules.programs`
+        - `inputs.NGIpkgs.nixosModules.services`
+


@ju1m , I just built the manual and I definitely don't think we should have configuration options listed on the home page as I see it now. Are you able to move them to separate (Configuration options) page ? Thanks.

ju1m · 2026-01-22T03:32:35Z

eljamm

Thank you for the awesome work, @ju1m, this looks really good! There are no blockers from me, only a few small comments. We can make followups for any improvements or refactors after we merge this.

imincik · 2026-01-22T12:26:37Z

@ju1m , I am getting following error when trying to build manual

nix -L build -f . manuals.singlehtml
error:
       … while calling the 'derivationStrict' builtin
         at <nix/derivation-internal.nix>:37:12:
           36|
           37|   strict = derivationStrict drvAttrs;
             |            ^
           38|

       … while evaluating derivation 'NGIpkgs-Manuals-singlehtml-26.05'
         whose name attribute is located at /nix/store/snxcfmlvhnkclvsd1rasskqhq0v0y7fh-source/pkgs/stdenv/generic/make-derivation.nix:541:13

       … while evaluating attribute 'patchPhase' of derivation 'NGIpkgs-Manuals-singlehtml-26.05'
         at /home/imincik/Projects/ngi/ngipkgs/code/manuals/default.nix:56:5:
           55|
           56|     patchPhase = ''
             |     ^
           57|       runHook prePatch

       (stack trace truncated; use '--show-trace' to show the full, detailed trace)

       error: attribute 'dirtyShortRev' missing
       at /home/imincik/Projects/ngi/ngipkgs/code/default.nix:18:43:
           17|   version = "26.05";
           18|   revision = flake.sourceInfo.shortRev or flake.sourceInfo.dirtyShortRev;
             |                                           ^
           19|

imincik · 2026-01-22T12:34:35Z

@ju1m ,

Remove all content from home page - we should populate it with some NGIpkgs introduction
Remove "XYZ as [PDF]" links on the left side and add link to "Configuration Options" page instead. I don't think we need PDFs.
Is it possible to add search to the left panel as we have at nix.dev ?

imincik · 2026-01-22T12:42:16Z

I have just discovered that singlehtml renders very differently to html. html result looks much better to me and it contains search. Maybe we should disable singlehtml then.

imincik

I have few small ideas for improvements but we can implement them in next PRs. Great work @ju1m . Thank you. Let's merge it.

github-project-automation Bot added this to Nix@NGI Dec 8, 2025

ju1m force-pushed the doc branch 3 times, most recently from e495d02 to 46a04d5 Compare December 10, 2025 10:50

imincik requested review from eljamm and imincik December 10, 2025 13:15

ju1m force-pushed the doc branch from 46a04d5 to bd0f2f8 Compare December 10, 2025 22:51

imincik reviewed Dec 11, 2025

View reviewed changes

imincik mentioned this pull request Dec 11, 2025

US: Documentation framework #1893

Closed

ju1m force-pushed the doc branch 4 times, most recently from 6d515aa to d81f918 Compare December 12, 2025 22:07

ju1m force-pushed the doc branch 3 times, most recently from c8a17b1 to 485707a Compare December 27, 2025 15:19

ju1m force-pushed the doc branch from 485707a to 1d4bdf9 Compare January 3, 2026 06:48

ju1m marked this pull request as ready for review January 6, 2026 06:34

ju1m force-pushed the doc branch from 1d4bdf9 to b84eeca Compare January 7, 2026 01:18

ju1m mentioned this pull request Jan 7, 2026

pkgs(bonfire): init at 1.0.1-beta.11 #1812

Merged

8 tasks

eljamm reviewed Jan 7, 2026

View reviewed changes

Comment thread manuals/default.nix Outdated

Comment thread manuals/default.nix Outdated

Comment thread manuals/default.nix Outdated

ju1m force-pushed the doc branch from b84eeca to 6129b42 Compare January 7, 2026 13:34

eljamm reviewed Jan 8, 2026

View reviewed changes

ju1m force-pushed the doc branch from 6129b42 to 3668c2e Compare January 8, 2026 22:08

ju1m mentioned this pull request Jan 8, 2026

build(doc): fix various things preventing to generate optionsDoc for services and programs. #1942

Merged

3 tasks

imincik linked an issue Jan 12, 2026 that may be closed by this pull request

Build initial web documentation interface (nix.dev like website) #1951

Closed

ju1m force-pushed the doc branch 2 times, most recently from 63240fa to c14a92d Compare January 12, 2026 13:05

ju1m mentioned this pull request Jan 12, 2026

doc(manuals): organize content #1954

Closed

1 task

ju1m force-pushed the doc branch from c14a92d to d62feef Compare January 13, 2026 07:39

eljamm reviewed Jan 13, 2026

View reviewed changes

phanirithvij mentioned this pull request Jan 19, 2026

feat: use numtide/devshell to improve devshell experience #1973

Merged

imincik requested changes Jan 19, 2026

View reviewed changes

ju1m force-pushed the doc branch from d62feef to cdfa9c4 Compare January 22, 2026 03:25

eljamm previously approved these changes Jan 22, 2026

View reviewed changes

Comment thread manuals/default.nix Outdated

Comment thread default.nix

Comment thread default.nix

feat(manuals): init sphinx framework based upon nix.dev

6a3c225

ju1m dismissed eljamm’s stale review via 6a3c225 January 22, 2026 11:49

ju1m force-pushed the doc branch from cdfa9c4 to 6a3c225 Compare January 22, 2026 11:49

imincik approved these changes Jan 22, 2026

View reviewed changes

imincik merged commit 3870756 into ngi-nix:main Jan 22, 2026
12 checks passed

github-project-automation Bot moved this to Done in Nix@NGI Jan 22, 2026

ju1m mentioned this pull request Jan 22, 2026

manuals: next #2010

Merged

2 tasks

ju1m deleted the doc branch January 22, 2026 16:19

jian-lin reviewed Feb 9, 2026

View reviewed changes

Comment thread manuals/Options.nix

jian-lin mentioned this pull request Feb 9, 2026

doc: support {.tip} admonition #2059

Merged

Conversation

ju1m commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

State

Related

RoadMap

Uh oh!

imincik left a comment

Choose a reason for hiding this comment

Uh oh!

imincik commented Dec 11, 2025

Uh oh!

eljamm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eljamm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

imincik commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ju1m commented Jan 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ju1m commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eljamm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imincik commented Jan 22, 2026

ju1m commented Dec 8, 2025 •

edited

Loading

imincik commented Jan 12, 2026 •

edited

Loading

ju1m commented Jan 22, 2026 •

edited

Loading