mirror of
https://github.com/nix-community/dream2nix.git
synced 2024-12-22 22:11:50 +03:00
add docs/README.md
This commit is contained in:
parent
361f402625
commit
b80a263443
67
docs/README.md
Normal file
67
docs/README.md
Normal file
@ -0,0 +1,67 @@
|
||||
# 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 ..#reference) ./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)
|
||||
|
||||
|
@ -9,6 +9,7 @@ nav:
|
||||
- "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
|
||||
- "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
|
||||
- "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
|
||||
- Documentation: docs.md
|
||||
- Notes:
|
||||
- "v1 API design docs": v1-api
|
||||
- development-roundups
|
||||
|
1
docs/src/docs.md
Symbolic link
1
docs/src/docs.md
Symbolic link
@ -0,0 +1 @@
|
||||
../README.md
|
Loading…
Reference in New Issue
Block a user