diff options
author | pennae <github@quasiparticle.net> | 2023-01-25 00:33:40 +0100 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2023-01-27 20:07:34 +0100 |
commit | 0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9 (patch) | |
tree | 6e28cb9ba90a3d03d6efab999b958527af45f84c /nixos/doc/manual/from_md/development/meta-attributes.section.xml | |
parent | 8b8670db100efed03a979f7ec24c353f72c0bdbd (diff) |
nixos/manual: render module chapters with nixos-render-docs
this converts meta.doc into an md pointer, not an xml pointer. since we no longer need xml for manual chapters we can also remove support for manual chapters from md-to-db.sh since pandoc converts smart quotes to docbook quote elements and our nixos-render-docs does not we lose this distinction in the rendered output. that's probably not that bad, our stylesheet didn't make use of this anyway (and pre-23.05 versions of the chapters didn't use quote elements either). also updates the nixpkgs manual to clarify that option docs support all extensions (although it doesn't support headings at all, so heading anchors don't work by extension).
Diffstat (limited to 'nixos/doc/manual/from_md/development/meta-attributes.section.xml')
-rw-r--r-- | nixos/doc/manual/from_md/development/meta-attributes.section.xml | 29 |
1 files changed, 5 insertions, 24 deletions
diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml index 450a5f670f3a8..64234f1cc0d7a 100644 --- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml +++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml @@ -28,7 +28,7 @@ meta = { maintainers = with lib.maintainers; [ ericsagnes ]; - doc = ./default.xml; + doc = ./default.md; buildDocsInSandbox = true; }; } @@ -42,8 +42,10 @@ </listitem> <listitem> <para> - <literal>doc</literal> points to a valid DocBook file containing - the module documentation. Its contents is automatically added to + <literal>doc</literal> points to a valid + <link xlink:href="https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup">Nixpkgs-flavored + CommonMark</link> file containing the module documentation. Its + contents is automatically added to <xref linkend="ch-configuration" />. Changes to a module documentation have to be checked to not break building the NixOS manual: @@ -51,27 +53,6 @@ <programlisting> $ nix-build nixos/release.nix -A manual.x86_64-linux </programlisting> - <para> - This file should <emphasis>not</emphasis> 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 - </para> - <programlisting> -$ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml -</programlisting> - <para> - 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 - </para> - <programlisting> -$ 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 -</programlisting> </listitem> <listitem> <para> |