diff options
| author | pennae <82953136+pennae@users.noreply.github.com> | 2023-01-30 19:26:07 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-01-30 19:26:07 +0100 |
| commit | 5b6dcece880b1fe45532b383e1c1f9574ddac4cf (patch) | |
| tree | 75ad5ae9002e3ff171eb95a0367456105bb7e121 /nixos/doc/manual/development | |
| parent | 8de8ee54bdceb257a05635e08c6021eb251720bd (diff) | |
| parent | 0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9 (diff) | |
Merge pull request #212684 from pennae/nixos-render-docs
nixos-render-docs: init, use for some manual rendering to docbook
Diffstat (limited to 'nixos/doc/manual/development')
| -rw-r--r-- | nixos/doc/manual/development/meta-attributes.section.md | 26 |
1 files changed, 4 insertions, 22 deletions
diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md index 7129cf8723e68..33b41fe74d297 100644 --- a/nixos/doc/manual/development/meta-attributes.section.md +++ b/nixos/doc/manual/development/meta-attributes.section.md @@ -23,7 +23,7 @@ file. meta = { maintainers = with lib.maintainers; [ ericsagnes ]; - doc = ./default.xml; + doc = ./default.md; buildDocsInSandbox = true; }; } @@ -31,7 +31,9 @@ file. - `maintainers` contains a list of the module maintainers. -- `doc` points to a valid DocBook file containing the module +- `doc` points to a valid [Nixpkgs-flavored CommonMark]( + https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup + ) file containing the module documentation. Its contents is automatically added to [](#ch-configuration). Changes to a module documentation have to be checked to not break building the NixOS manual: @@ -40,26 +42,6 @@ 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 |