mirror of
https://github.com/nix-community/dream2nix.git
synced 2024-12-23 14:31:55 +03:00
68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# About this Documentation
|
|
|
|
Dream2nix documentation is generated from markdown via
|
|
[mkdocs](https://www.mkdocs.org/) and [mkdocs-material](https://squidfunk.github.io/mkdocs-material/).
|
|
|
|
## Build
|
|
|
|
You can build and server it locally with, i.e.:
|
|
|
|
``` shellsession
|
|
nix build .#website
|
|
python3 -m http.server -d ./result
|
|
```
|
|
|
|
# Development shell
|
|
|
|
Or alternatively run a development environment with:
|
|
|
|
``` shellsession
|
|
nix develop .#website
|
|
```
|
|
|
|
Upon entering the devshell, it will change into
|
|
`./docs` and symlink a build of the [options reference](#options-reference)
|
|
into `./docs/src/reference`.
|
|
|
|
Normal builds will always use an up-to-date options reference,
|
|
but during development you need to update this symlink yourself
|
|
and remove it after use.
|
|
|
|
i.e. from inside the shell in `./docs`:
|
|
|
|
``` shellsession
|
|
# update
|
|
ln -sfT $(nix build --print-out-paths --no-link ..#optionsReference) ./src/reference
|
|
# remove
|
|
rm ./src/reference
|
|
```
|
|
|
|
## Options Reference
|
|
|
|
The reference documentation for [modules](./modules.md) is auto-generated via
|
|
a custom hook in `docs/hooks/render_options.py` and a derivation in
|
|
`.#optionsReference`.
|
|
|
|
The derivation includes, for each module, an `options.json` file as generated by nix via `pkgs.nixosOptionsDoc` as well as a `README.md` file, copied from the modules source directory. The existence of such a `README.md` is used as an indicator on whether to include a module in the reference documentation.
|
|
|
|
The hook runs whenever mkdocs renders one of the `README.md`s. Each of them gets concatenated with header and options reference, after the latter are run through jinja templates in `./docs/theme`.
|
|
|
|
|
|
## Notes on Markdown
|
|
|
|
Mkdocs uses a markdown dialect from [Python-Markdown](https://python-markdown.github.io/) with various, optional extensions listed in `./docs/mkdocs.yml`.
|
|
|
|
This is different from the CommonMark dialect, as implemented by [markdown-it-py](https://pypi.org/project/markdown-it-py/) and used in NixOS official documentation.
|
|
|
|
The differences between both don't seem to be too relevant for the markdown features used in our [options reference](#options-reference), but it's good
|
|
to be aware of them when writing longer prose.
|
|
|
|
[mkdocs-materials reference](https://squidfunk.github.io/mkdocs-material/reference) provides a
|
|
good overview on useful extensions.
|
|
|
|
## CI
|
|
|
|
The documentation is published on GitHub pages via a GitHub action, defined in [.github/workflows/pages.yml](https://github.com/nix-community/dream2nix/blob/main/.github/workflows/pages.yml)
|
|
|
|
|