chore: move docgen comment to markdown file

docs/default.nix

@@ -1,26 +1,3 @@
-# Documentation
-/**
-  Docs are generated from comments in `.nix` files.
-  This results in kind of weird config format, but
-  makes it easier to track configuration changes
-  and add/remove docs as required.
-
-  ## How docs are generated
-
-  `nixdoc` utility enables us to generate documentation
-  from comments in `.nix` file, like `doxygen` and `rustdoc` do.
-
-  `nixdoc` requires this flags:
-  - category (derived from file's path)
-  - description (derived from file's first line if it's commented)
-
-  most hard part is to generate SUMMARY.md.
-  generator uses orderKey of type "{num}|{mdPath}" and derives indentation from path's depth,
-  so chapters have proper order.
-
-  run `nix build .#docBuild` to build documentation.
-  run `nix run .#docServe` to serve documentation site
-*/
 {
   perSystem =
     { pkgs, ... }:

docs/docgen.nix

@@ -16,8 +16,7 @@ stdenvNoCC.mkDerivation {
       excluded = [
         ".*flake\\.nix$"
 
-        "docs/docgen.nix"
-        "docs/server.nix"
+        "^docs/.*"
       ];
 
       shouldExclude = relPath: lib.any (pattern: builtins.match pattern relPath != null) excluded;
@@ -93,7 +92,13 @@ stdenvNoCC.mkDerivation {
 
       summaryContent =
         "# Summary\n\n"
-        + "[Introduction](README.md)\n"
+        + ''
+          [Introduction](README.md)
+
+          - [Features]()
+            - [Documentation generation](docGen.md)
+
+        ''
         + builtins.concatStringsSep "\n" (map (c: c.summaryLine) chapters)
         + "\n";
 

docs/src/docGen.md

@@ -0,0 +1,21 @@
+# Documentation
+Docs are generated from comments in `.nix` files.
+This results in kind of weird config format, but
+makes it easier to track configuration changes
+and add/remove docs as required.
+
+## How docs are generated
+
+`nixdoc` utility enables us to generate documentation
+from comments in `.nix` file, like `doxygen` and `rustdoc` do.
+
+`nixdoc` requires this flags:
+- category (derived from file's path)
+- description (derived from file's first line if it's commented)
+
+most hard part is to generate SUMMARY.md.
+generator uses orderKey of type `{num}|{mdPath}` and derives indentation from path's depth,
+so chapters have proper order.
+
+run `nix build .#docBuild` to build documentation.
+run `nix run .#docServe` to serve documentation site