Markup syntax in comments

[tazjin]

(Warning: This thread may contain bikeshedding!)

---

It would be nice to have support for some markup format in documentation strings. The easiest one that everybody knows is Markdown. It's very easy to use pulldown-cmark to implement a custom emitter for the format, too, so this seems very tempting.

There are some existing comments that use a slightly different syntax for inline code blocks though:

This line has `inline code'.

Maybe it's possible to make this work in the Markdown parser, but if not I think it's probably easier to just change those comments.

[roberth]

Let's please avoid bikeshedding. This issue is a serious question and the decision will have real consequences.

Please also keep in mind that the choice of documentation format will need support from the community in order for this tool to be effective.
Considering that earlier attempts to solve this problem with tooling have stalled due to the lack of a decision about the format, it is probably best to avoid duplicating work until a decision has been made.

I am very hopeful about the new RFC process. It seems that the Nix community will be able to actually decide on RFCs more effectively, which is needed. It also seems to be the only way that this decision can be made.

---

For reference, here are some efforts that have stalled due to a lack of decision:

• IIRC @grahamc wrote a prototype tool once that extracted comments
• @grahamc wrote a system that uses nix to document library functions, similar to how NixOS options are documented
• Similarly my nix repl docstrings PR that I wrote at last year's hackday
• Probably others that I'm unaware of

[tazjin]

Here are my current thoughts on the topic:

What we have right now

People have over time converged onto a relatively common structure for comments, which is what nixdoc currently parses:

/* The actual documentation string goes at the beginning of a multi-line
   comment.

   Sometimes people write multiple paragraphs.

   Type: one-line faux type signature

   Example:
     # indented code example after the 'Example' word
     some code;
     # people use the "result arrow" to denote the expected return
     => 42
*/
someFn = ...;

Inside of the documentation string at the beginning, some people are currently using Markdown-like syntax, I've seen:

*emphasis with stars*
`inline code with backticks`

Some open inline code with a backtick, close it with an apostrophe (like in Lisp). In my doc comments updates I've changed those to backtick-only, so for the files I touched it is now consistent.

What we actually need

We need to have the following features to support what we can generate right now, and also to do what we want to in the future:

1. Syntax for "type signatures".
2. Syntax for multiple named examples.
3. Syntax for specifying expected results in examples.
4. Syntax to skip running doctests for an example.
5. Syntax for referencing other documentation items.
6. Nice to have: Simple markup (emphasis, bold, inline code).

Please extend this list if you can think of more things (cc: @grahamc).

I do not think that a complex format that supports all of what DocBook has to offer should be supported in the doc comments. These will be consumed both by people reading the source (so they should read naturally) and the web manual, and they should be writeable without having to learn anything significant.

nixdoc has an escape hatch for manually written documentation for functions, if some complex thing is required.

Prior art & inspiration

Just dumping a few things that I can think of, feel free to add more to the list!

1. Rust

   @edolstra mentioned in his keynote that he likes how the Rust team is working and they have faced this same issue before, resulting in Rust RFC 0505 and RFC 1574 which specify the Markdown-based rustdoc comment syntax.

   I tried to find older Rust-team discussions about this to see what arguments were made to settle on that, but couldn't find it from a cursory googling. Maybe someone from the Rust team (@steveklabnik maybe?) could point us towards some info about that, because I think that the considerations made for Rust would to a large degree also apply to Nix.

2. Haskell

   Haskell's Haddock has a totally custom markup format that supports all of the use-cases they had. This is nice in some ways, but in my personal experience with Haddock it means that I have to go and look up the markup syntax all the time.

3. Elixir

   Elixir uses Markdown in their documentation annotations. The fact that the annotations are actually specific syntax is also interesting, but that is way out of scope for this issue & topic. I haven't found any discussion about why Markdown was chosen specifically, but have also not looked too deeply into it.

Note: This also vaguely relates to nix-community/flake.nix#2 - it would be nice to go in the same direction in both projects for future compatibility. (cc: @shlevy).

[shlevy]

FWIW, for now I'm leaning heavily in the direction of RST for nix-community/flake.nix#2 . It covers the common cases really nicely but has facilities for arbitrarily rich semantics layered on top if we need it. Ultimately though my plan is to defer to the RFC process if/when prototypes have proven their worth and we're ready to go live.

[tazjin]

Here is some interesting discussion from the Rust community about reStructuredText.

[shlevy]

Yeah, in domains where markdown is adequate (which probably holds for the vast majority of docstrings) it's probably the best choice. Good luck to the brave soul who wants to reimplement the nix manuals in it, though 😉

[tazjin]

Good luck to the brave soul who wants to reimplement the nix manuals in it, though 😉

I for one want to be very clear that this issue is not about the manual at large, but about docstrings specifically. The manual obviously has very different requirements! 🙃

[edolstra]

I'm not a fan of RST, which has all the "do what I mean" syntax issues common to all markdown-like languages. (E.g. you have to remember what magic number of spaces causes an indented block, what magic characters introduce a section/subsection/italics etc.)

[shlevy]

@tazjin Yeah, sorry to muddy the waters here. Was just noting that because it collides with nix-community/flake.nix#2

[roberth]

Yeah, in domains where markdown is adequate (which probably holds for the vast majority of docstrings) it's probably the best choice. Good luck to the brave soul who wants to reimplement the nix manuals in it, though

This aged well.

Considering that the manual is markdown now, am I wrong to assume we don't need to specify anything on top of what we already do in the rest of the manual?

[jtojnar]

@roberth The Nix manual was a huge downgrade in some aspects of UX. Compare https://nixos.org/manual/nix/stable/#builtin-fetchGit with https://nixos.org/manual/nix/unstable/expressions/builtins.html – you cannot even link to individual functions any more.

So at minimum, we need anchor support. In Nixpkgs manual, we borrowed pandoc’s heading indentifiers (likewise for inline anchors).

Additionally, it would be nice to have a better syntax for the actual function descriptions. Currently:

• Some Nixpkgs manual sections use definition lists.
  • These best correspond to varlistentry but are non-standard and use significant whitespace so are pain to work with. Also need to use inline anchors.
• Nix manual uses unordered lists (example).
  • Same downsides as definition lists and also uglier but at least they are wildly supported.
• Some Nixpkgs manual sections use headings.
  • These hold middle ground in ugliness and heading identifiers are slightly more common in markdown implementations.
  • Since one does not need to bother with whitespace, I ended up choosing these for the stdenv port.

[edolstra]

So at minimum, we need anchor support.

No, we don't. The whole point of switching to Markdown is to make it easier to contribute. If we reinvent Docbook markup (poorly, using line noise as markup), then we haven't really gained anything.

Generated docs can have anchors though, it's just that we don't want to write them in Markdown.

[fricklerhandwerk]

Is there anything speaking against using any strict subset of markdown that is already in Nixpkgs? As long as there are no diverging features, people can use common things such as inline code. It should be fine not for everything to work right now, and we can still add an implementation that allows for the same extensions as in the rest of the manual.

[infinisil]

This is done now with @pennae's efforts in #40 and NixOS/nixpkgs#239636 🚀