docs/server: refactor & improve serve-docs; add nix run .#docs

CONTRIBUTING.md

@@ -13,6 +13,14 @@ In order to submit a change you must be careful of several points:
 - The commit title should be consistent with our style. This usually looks like "plugins/<name>: fixed some bug",
   you can browse the commit history of the files you're editing to see previous commit messages.
 
+### Testing the docs locally
+
+When making a change, you may wish to see how it looks in Nixvim's documentation.
+This can be done by running `nix run .#docs` from within a Nixvim repo.
+Alternatively, if you've entered a Nixvim dev shell, you can run `serve-docs`.
+
+Either command will start a HTTP server on port 8000 and open it in your browser using `xdg-open`.
+
 ## Nixvim Architecture
 
 Nixvim is mainly built around `pkgs.neovimUtils.makeNeovimConfig`.

docs/default.nix

@@ -132,5 +132,9 @@ lib.fix (
       inherit evaledModules transformOptions;
       inherit (self) search lib-docs;
     };
+
+    serve-docs = pkgs.callPackage ./server {
+      inherit (self) docs;
+    };
   }
 )

docs/server/default.nix

@@ -0,0 +1,21 @@
+{
+  lib,
+  runCommand,
+  makeBinaryWrapper,
+  python3,
+  xdg-utils,
+  docs,
+}:
+runCommand "serve-docs"
+  {
+    nativeBuildInputs = [ makeBinaryWrapper ];
+    meta.mainProgram = "server";
+  }
+  ''
+    mkdir -p $out/bin
+    makeWrapper ${lib.getExe python3} \
+        $out/bin/server \
+        --add-flags ${./server.py} \
+        --chdir ${docs} \
+        --prefix PATH : ${lib.makeBinPath [ xdg-utils ]}
+  ''

docs/server/server.py

@@ -0,0 +1,25 @@
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from subprocess import call
+
+PORT = 8000
+URL = f"http://localhost:{PORT}"
+
+
+class AutoBrowseHTTPServer(HTTPServer):
+    def server_activate(self):
+        HTTPServer.server_activate(self)
+        print(f"Serving documentation at {URL}")
+        call(["xdg-open", URL])
+
+
+class UncachedHTTPHandler(SimpleHTTPRequestHandler):
+    def end_headers(self):
+        self.send_header("Cache-Control", "no-cache, no-store, must-revalidate")
+        self.send_header("Pragma", "no-cache")
+        self.send_header("Expires", "0")
+        super().end_headers()
+
+
+if __name__ == "__main__":
+    with AutoBrowseHTTPServer(("", PORT), UncachedHTTPHandler) as httpd:
+        httpd.serve_forever()

flake/dev/devshell.nix

@@ -101,14 +101,7 @@
               help = "Build and serve documentation locally";
               command = ''
                 echo -e "=> Building nixvim documentation...\n"
-
-                doc_derivation=$(${nix} build .#docs --no-link --print-out-paths)
-
-                echo -e "\n=> Documentation successfully built ('$doc_derivation')"
-
-                echo -e "\n=> You can then open your browser to view the doc\n"
-
-                (cd "$doc_derivation"/share/doc && ${pkgs.lib.getExe pkgs.python3} ${./server.py})
+                nix run .#docs
               '';
             }
             {

flake/packages.nix

@@ -7,11 +7,15 @@
 {
   perSystem =
     {
+      config,
       inputs',
       system,
       ...
     }:
     {
+      # Run the docs server when using `nix run .#docs`
+      apps.docs.program = config.packages.serve-docs;
+
       packages = import ../docs {
         nixvim = self;
         inherit helpers;