diff options
author | pennae <github@quasiparticle.net> | 2023-01-04 09:02:21 +0100 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2023-01-10 10:31:59 +0100 |
commit | 785c0f2afaa326f45e6c2cfc83e257278f80a001 (patch) | |
tree | 2d05fa3fe16c4dc3603039dc44511f12e37fa1ed /nixos/doc/manual/development/meta-attributes.section.md | |
parent | 23ea73b4169d68c0d22c3d9aed6e2a692a793ff5 (diff) | |
download | nixpkgs-785c0f2afaa326f45e6c2cfc83e257278f80a001.tar nixpkgs-785c0f2afaa326f45e6c2cfc83e257278f80a001.tar.gz nixpkgs-785c0f2afaa326f45e6c2cfc83e257278f80a001.tar.bz2 nixpkgs-785c0f2afaa326f45e6c2cfc83e257278f80a001.tar.lz nixpkgs-785c0f2afaa326f45e6c2cfc83e257278f80a001.tar.xz nixpkgs-785c0f2afaa326f45e6c2cfc83e257278f80a001.tar.zst nixpkgs-785c0f2afaa326f45e6c2cfc83e257278f80a001.zip |
nixos/manual: mention that module chapters should use markdown
Diffstat (limited to 'nixos/doc/manual/development/meta-attributes.section.md')
-rw-r--r-- | nixos/doc/manual/development/meta-attributes.section.md | 20 |
1 files changed, 20 insertions, 0 deletions
diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md index 946c08efd0a..7129cf8723e 100644 --- a/nixos/doc/manual/development/meta-attributes.section.md +++ b/nixos/doc/manual/development/meta-attributes.section.md @@ -40,6 +40,26 @@ file. $ nix-build nixos/release.nix -A manual.x86_64-linux ``` + This file should *not* usually be written by hand. Instead it is preferred + to write documentation using CommonMark and converting it to CommonMark + using pandoc. The simplest documentation can be converted using just + + ```ShellSession + $ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml + ``` + + More elaborate documentation may wish to add one or more of the pandoc + filters used to build the remainder of the manual, for example the GNOME + desktop uses + + ```ShellSession + $ pandoc gnome.md -t docbook --top-level-division=chapter \ + --extract-media=media -f markdown+smart \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \ + --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \ + > gnome.xml + ``` + - `buildDocsInSandbox` indicates whether the option documentation for the module can be built in a derivation sandbox. This option is currently only honored for modules shipped by nixpkgs. User modules and modules taken from |