incus: build and expose documentation

nixos/modules/virtualisation/incus.nix

@@ -129,6 +129,7 @@ let
 
   environment = lib.mkMerge [
     {
+      INCUS_DOCUMENTATION = "${cfg.package.doc}/html";
       INCUS_EDK2_PATH = ovmf;
       INCUS_LXC_HOOK = "${cfg.lxcPackage}/share/lxc/hooks";
       INCUS_LXC_TEMPLATE_CONFIG = "${pkgs.lxcfs}/share/lxc/config";

nixos/tests/incus/ui.nix

@@ -66,6 +66,7 @@ import ../make-test-python.nix (
 
     testScript = ''
       machine.wait_for_unit("incus.service")
+      machine.wait_for_unit("incus-preseed.service")
 
       # Check that the INCUS_UI environment variable is populated in the systemd unit
       machine.succeed("systemctl cat incus.service | grep 'INCUS_UI'")
@@ -73,6 +74,9 @@ import ../make-test-python.nix (
       # Ensure the endpoint returns an HTML page with 'Incus UI' in the title
       machine.succeed("curl -kLs https://localhost:8443/ui | grep '<title>Incus UI</title>'")
 
+      # Ensure the documentation is rendering correctly
+      machine.succeed("curl -kLs https://localhost:8443/documentation/ | grep '<title>Incus documentation</title>'")
+
       # Ensure the application is actually rendered by the Javascript
       machine.succeed("PYTHONUNBUFFERED=1 selenium-script")
     '';

pkgs/by-name/in/incus/docs.patch

@@ -0,0 +1,26 @@
+diff --git i/doc/conf.py w/doc/conf.py
+index 8d042818b..b4f0572bd 100644
+--- i/doc/conf.py
++++ w/doc/conf.py
+@@ -8,10 +8,6 @@ import yaml
+ from git import Repo
+ import filecmp
+ 
+-# Download and link swagger-ui files
+-if not os.path.isdir('.sphinx/deps/swagger-ui'):
+-    Repo.clone_from('https://github.com/swagger-api/swagger-ui', '.sphinx/deps/swagger-ui', depth=1)
+-
+ os.makedirs('.sphinx/_static/swagger-ui/', exist_ok=True)
+ 
+ if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-bundle.js'):
+@@ -151,10 +147,6 @@ if os.path.exists("./related_topics.yaml"):
+     with open("./related_topics.yaml", "r") as fd:
+         myst_substitutions.update(yaml.safe_load(fd.read()))
+ 
+-intersphinx_mapping = {
+-    'cloud-init': ('https://cloudinit.readthedocs.io/en/latest/', None)
+-}
+-
+ if ("LOCAL_SPHINX_BUILD" in os.environ) and (os.environ["LOCAL_SPHINX_BUILD"] == "True"):
+     swagger_url_scheme = "/api/#{{path}}"
+ else:

pkgs/by-name/in/incus/generic.nix

@@ -13,6 +13,7 @@
   buildGoModule,
   fetchFromGitHub,
   acl,
+  buildPackages,
   cowsql,
   incus-ui-canonical,
   libcap,
@@ -27,11 +28,30 @@
 
 let
   pname = "incus${lib.optionalString lts "-lts"}";
+  docsPython = buildPackages.python3.withPackages (
+    py: with py; [
+      furo
+      gitpython
+      linkify-it-py
+      canonical-sphinx-extensions
+      myst-parser
+      pyspelling
+      sphinx
+      sphinx-autobuild
+      sphinx-copybutton
+      sphinx-design
+      sphinx-notfound-page
+      sphinx-remove-toctrees
+      sphinx-reredirects
+      sphinx-tabs
+      sphinxcontrib-jquery
+      sphinxext-opengraph
+    ]
+  );
 in
 
-buildGoModule rec {
+buildGoModule (finalAttrs: {
   inherit
-    patches
     pname
     vendorHash
     version
@@ -40,15 +60,18 @@ buildGoModule rec {
   outputs = [
     "out"
     "agent_loader"
+    "doc"
   ];
 
   src = fetchFromGitHub {
     owner = "lxc";
     repo = "incus";
-    rev = "refs/tags/v${version}";
+    tag = "v${version}";
     inherit hash;
   };
 
+  patches = [ ./docs.patch ] ++ patches;
+
   excludedPackages = [
     # statically compile these
     "cmd/incus-agent"
@@ -61,6 +84,7 @@ buildGoModule rec {
   nativeBuildInputs = [
     installShellFiles
     pkg-config
+    docsPython
   ];
 
   buildInputs = [
@@ -82,6 +106,13 @@ buildGoModule rec {
   CGO_LDFLAGS_ALLOW = "(-Wl,-wrap,pthread_create)|(-Wl,-z,now)";
 
   postBuild = ''
+    # build docs
+    mkdir -p .sphinx/deps
+    ln -s ${buildPackages.python3.pkgs.swagger-ui-bundle.src} .sphinx/deps/swagger-ui
+    substituteInPlace Makefile --replace-fail '. $(SPHINXENV) ; ' ""
+    make doc-incremental
+
+    # build some static executables
     make incus-agent incus-migrate
   '';
 
@@ -111,18 +142,20 @@ buildGoModule rec {
     cp internal/server/instance/drivers/agent-loader/systemd/incus-agent.service $agent_loader/etc/systemd/system/
     cp internal/server/instance/drivers/agent-loader/systemd/incus-agent.rules $agent_loader/lib/udev/rules.d/99-incus-agent.rules
     substituteInPlace $agent_loader/etc/systemd/system/incus-agent.service --replace-fail 'TARGET/systemd' "$agent_loader/bin"
+
+    mkdir $doc
+    cp -R doc/html $doc/
   '';
 
   passthru = {
     client = callPackage ./client.nix {
       inherit
         lts
-        meta
         patches
-        src
         vendorHash
         version
         ;
+      inherit (finalAttrs) meta src;
     };
 
     tests = if lts then nixosTests.incus-lts.all else nixosTests.incus.all;
@@ -143,4 +176,4 @@ buildGoModule rec {
     platforms = lib.platforms.linux;
     mainProgram = "incus";
   };
-}
+})