Any consensus on documentation generation tool for nixpkgs manual?

Which syntax feature were you trying to add?

inline roles, eg {manpage}`nix.conf(5)`.

can we have a .info for opening on emacs as well? guix has that and it so lovely being able to use emacs for guix documentation

1 Like

@ryantm why is closure size an issue for nixpkgs doc but not for nix doc?

I like about mmdoc is that it generates single and multi page documentation.
I think a few useful things are not part of mmdoc:

footnotes

footnotes[^examplefn]

(partial) file inclusion

like in mdbook: mdBook-specific features - mdBook Documentation

mermaid diagrams

example: https://github.com/nixOS/nix-book#a-vision-for-the-journey-into-nix-nixpkgs-and-nixos

Definition List

term
: definition
(good for glossary)

Strikethrough

The world is flat.
to be able to write down mistakes without confusing tired readers

Task List

  • parse markdown
  • add task lists

and maybe less important:
Subscript: H~2~O
Superscript: X^2^

[^examplefn]: footnotes are helpful
to add additional information
and references.
pandoc implements two styles Pandoc - Pandoc User’s Guide

For nix and nixpkgs manuals, the build closure size is not as important. For the NixOS manual is it is, because we build the manual as part of realizing the system (nixos-rebuild). If the user adds their own NixOS module options, they show up in the manual. Currently the manual is built by default on all NixOS systems. If we chose to optionally build it, then the closure size would be less important.

mmdoc has Definition Lists. We should be careful about adding a bunch of extensions on top of CommonMark, since that moves us spiritually farther away from the documentation format RFC, and also makes it less likely we can easily port the manual to a different backend.

agreed, but we should also not decrease the quality of documentation output. so far we’ve been trying to introduce only the minimal set of extensions necessary to keep current docs rendering the same (where the manpage notably makes more distinctions than the html manual). adding an extension for everything docbook offers won’t do, but a few (on top of what we already have) should be okay.

Hosted by Flying Circus.