31 lines
995 B
Nix
31 lines
995 B
Nix
# 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, ... }:
|
|
rec {
|
|
packages.docBuild = pkgs.callPackage ../docs/docgen.nix { };
|
|
packages.docServe = pkgs.callPackage ../docs/server.nix { doc = packages.docBuild; };
|
|
};
|
|
}
|