Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC 0064] New Documentation Format for nixpkgs and NixOS #64

Closed
wants to merge 26 commits into from
Closed

[RFC 0064] New Documentation Format for nixpkgs and NixOS #64

Changes from 24 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
e5985d6
Initial draft
infinisil Dec 31, 2019
fba7406
Move to correct location
infinisil Jan 5, 2020
cb6929c
Move the poll higher up
infinisil Jan 5, 2020
7c4c8a4
Mention that poll answers can be changed while open
infinisil Jan 5, 2020
443698b
Specify CommonMark
infinisil Jan 6, 2020
7560aca
Add a short overview of markdown
infinisil Jan 6, 2020
9df0d02
Build requirements into the process, list some requirements
infinisil Jan 6, 2020
b68de43
Add texinfo as a potential candidate
infinisil Jan 6, 2020
8c44064
Add Nix EDSL
infinisil Jan 6, 2020
1b7c25e
other prompts non-copyable
infinisil Jan 7, 2020
999b91b
Add some more requirements and an article suggested by @domenkozar
infinisil Jan 7, 2020
690d9b2
rewrite motivation
FRidh Jan 7, 2020
ca700a7
minor changes in requirements
FRidh Jan 7, 2020
7a2626d
Extend restructuredtext section
FRidh Jan 7, 2020
1d15ed4
Add comparison of tools, showing closure size
FRidh Jan 7, 2020
29bd249
Describe sphinx domains
FRidh Jan 7, 2020
81bd8ac
Refer to closure size ticket
FRidh Jan 7, 2020
c8bfa59
rfc 64 (#1)
infinisil Jan 7, 2020
5ca448d
Integrate feedback
infinisil Jan 11, 2020
3eeeda9
shepherds have the final word, only using poll as an input
infinisil Jan 11, 2020
85c1736
Add LLVM as another example for reST
energizah Feb 26, 2020
03607ef
Merge pull request #2 from energizah/patch-1
infinisil Feb 26, 2020
46fdccc
Add PowerDNS as ReST user example
nlewo Mar 2, 2020
31cb204
Merge pull request #3 from nlewo/powerdns
infinisil Mar 6, 2020
25e4a5a
Fill in shepherds
infinisil Apr 23, 2020
c96efe0
Update rfcs/0064-documentation-format.md
domenkozar May 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 202 additions & 0 deletions rfcs/0064-documentation-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
---
feature: documentation-format
start-date: 2019-12-31
author: Silvan Mosberger (infinisil)
co-authors: (find a buddy later to help out with the RFC)
shepherd-team: (names, to be nominated and accepted by RFC steering committee)
shepherd-leader: (name to be appointed by RFC steering committee)
infinisil marked this conversation as resolved.
Show resolved Hide resolved
related-issues: (will contain links to implementation PRs)
---

# Summary
[summary]: #summary

Many people from the Nix community are interested in evaluating alternatives to DocBook as the documentation format for nixpkgs/NixOS.
Through the process of this RFC, a potentially new doc format will be decided.

# Motivation
[motivation]: #motivation

The current doc format for nixpkgs (including NixOS) is DocBook, which has seen a lot of criticism over the years.
With a more approachable and well-known documentation format we expect to have more doc contributions from more people.
This should improve our docs to be more up-to-date and complete.

# Detailed design
[design]: #detailed-design

The process for determining the doc format is as follows:
- A set of requirements for the doc format is decided through the RFC discussion
- Doc format candidates are collected and evaluated to see if they fulfil the requirements. This should include a small demonstration
- A short objective overview of each valid candidate format is written, along with their advantages/disadvantages
- A [Discourse](https://discourse.nixos.org/) post is created with these overviews, along with a poll such that people can vote on the formats they prefer. This poll will be open to the whole community and should be advertised as such
- With the result of the poll as an input, the shepherd team decides on a doc format to be used. This decision is added to the RFC, after which it is merged.
- People are then free to work towards that new documentation format and the committers of nixpkgs must not oppose these efforts due to the format choice

## Poll
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think poll is too vague, people should discuss on this RFC exactly what they'd like and then the shepherd team makes a decision.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's important to involve as many people from the community as possible, because they will be the ones writing and reading the docs. Unfortunately RFC's are known to be bad places for involving many people, since they tend to get long quickly and less-active people get overshadowed by very vocal people.

As you suggested to me though, having the poll happen before the RFC is accepted and using it as an input for the shepherd team might be a good idea.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed the RFC to reflect this

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t like the poll idea. It’s too easy to vote for your favourite documentation format without considering the implications for our use case in Nixpkgs, which the most popular format might not be suited for.

It’s difficult to reasonably argue this without mentioning specific formats — I think it’s unreasonable to believe that formats and decision-making processes are unrelated. I think we all know which format is going to win a popularity contest, but that doesn’t mean it’s the best choice for Nixpkgs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summarizing from the discussion we had on IRC:

  • We need to make sure Markdown (and all others) can actually work as a format first with a small demo showing all the required features. Only if that is successful it can be a candidate. Sounds like a good idea to have small demos before the poll
  • This might need some extensions to "standard" markdown, which themselves should be as standard as possible. We ideally shouldn't have our own "Nix flavored Markdown". E.g. Sphinx provides a bunch of extensions by default already
  • If Markdown ends up in the poll, it might very well be a popularity contest, but that's not a bad thing, because everybody who knows markdown already won't have to learn many new things to contribute docs. We might have to educate people about how to use the extensions though


Since documentation needs to be written and read by the many people from the community, we should incorporate them as possible into this important decision. Discussions in RFCs aren't optimal for this, since not many people are willing to comment, meaning the few people with the strongest opinion will be the main participants, in addition to GitHub's comment section being very annoying to navigate. Because of this, a public poll on Discourse is held instead, allowing many people to easily give their preferences.

The poll is of the following form:
- Multiple-choice, allowing people to select all formats they agree with
- Results are only shown when the poll is closed for it to not be influenced by non-final tallies
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can the person who creates the poll see the tallies before-hand? If so, it would be good if the person who opens the poll explicitly discloses this in the conversation.

I'm also OK with removing the "secret-tally" requirement, as I'm not convinced it actually influences people's opinions as much, in this case - especially in a multiple-choice poll.

- Answers can be changed while the poll is still active, allowing people to discuss about formats and change their opinion (this is not optional in Discourse)
- It runs for 1 month to give enough time for less-active people to see it
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think 1 month is not enough for such a massive (and controversial change).

I propose 2 months.

- Who voted for which options is made public (Only possible with bar chart in Discourse) TODO: Do we want this or not? Why would we?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it can be useful to know where people stand (as there will surely be people who will vote without participating in the discussion) and to know whom to ask for help. And this is not one of those controversial or deeply personal topics that I think warrant anonimity honestly. It's a documentation format! 😂


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we allow for people to vote on all options, or should we restrict that as basically an "I don't care" and not count the vote at all?

I think it's still valuable to tally in those people who don't care, but who still took the effort to vote - it's still a sign of participation in the community.

## Requirements

- Can be converted to HTML and man pages
- Inter-file references for being able to link to options from anywhere
domenkozar marked this conversation as resolved.
Show resolved Hide resolved
- Ability to create link anchors to most places such that we can link to e.g. paragraphs
- Widespread editor integration featuring at least highlighting and preferably live-view
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Live-view is kind of a high-bar in my opinion, e.g. vim doesn't really have Markdown live-view AFAIK - and that's for the most popular markup format.

I suggest we remove it from the requirements (also because "preferably" doesn't really make sense in this section if we interpret Requirements strictly) and move it to Nice-to-have's.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think that we should decide that based on the limits of certain editors. If vim doesn't offer live-view feature, then let's check editors that do.

Getting instant feedback when doing any work really reduces the time needed to get something done and since documentation is already such a pain to write, I think this is key to getting more contributions.

Most formats offer live preview via a plugin.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If vim doesn't offer live-view feature, then let's check editors that do.

What do you mean by that? I think a format/feature that is not well supported by Vim is, realistically, not a good choice for a requirements section - unless we plan on implementing it ourselves.

That's why, incidentally, I think org-mode doesn't belong to this list, as much as I like it.

- Good error detection in toolchain and editors, e.g. with a fast and good processor
- Is decently fast to fully generate, in the range of 10 seconds for the full documentation on an average machine
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • supports syntax highlighting (of Nix)
  • wide editor integration (this could be added to the errors bullet point)
  • active community supporting the tooling infrastructure
  • good conversion story from docbook
  • ideally a good search integration
  • low work cost for integration (this one is really important as docbook fails hard)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, what do you mean by the last point though? That we don't need to write too many customizations and supporting code to make it work?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we qualify average machine, also for posterity's sake? How about the current MacBook Air that retails for USD1099 according to Wikipedia? I'm also fine with say Thinkpad T420.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And full documentation == nixpkgs?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest that "cheapest widely available refurbished business laptop at the time" would be a good way to define "average machine".

These things are ubiquitous (also due to their affordability, ~200 EUR is typical), are often representative of computing hardware from a generation or 2-3 ago in general, seem to have remained a reliable metric for this over the past 10 years, and in my experience the available offerings are quite consistent across countries, too.

- Closure-size of toolchain should be [small](https://github.com/NixOS/nixpkgs/issues/63513).
- Supports syntax highlighting (with Nix support)
- Active community supporting the tooling infrastructure
- Good conversion story from Docbook
- Can be used and integrated from NixOS option declarations

### Nice-to-have's

- Annotations/links inside code listings for e.g. linking to option docs in `configuration.nix` snippets
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How is this different from Inter-file references for being able to link to options from anywhere?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shooting from the hip... I think it describes the same behavior from a reader's perspective, but it means the engine is doing more than identifying a code block, a syntax type, and handing it off to the appropriate highlighter.

You have to parse (or at least partially parse) code blocks at build time, identify the different entities they contain, and use heuristics or direct lookups to resolve those local code entities into absolute paths to the appropriate documentation.

If the highlighter isn't collaborating in this work, it probably also entails postparsing the highlighted blocks to inject the links, and potentially modifying the stylesheets to make sure the links don't stomp all over the syntax highlighting.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds complicated :)

Are there examples of documentation format parsers doing this?

- Ability to make `$ `, `nix-repl>` and other prompts in command line snippets non-copyable
- Good search integration, e.g. by providing a well-functioning search field
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this about the output format having a search field?


## Format Candidates

All format candidates are listed here with links to demonstrations showing off required features and to get a feel for it. Any tooling can be used to achieve this.
Ideally this should consist of a standalone repository created for this purpose, not a nixpkgs fork.

| Format | Source | Rendered |
| --- | --- | --- |
| Markdown | TODO | TODO |
| reST | TODO | TODO |
| Asciidoc | TODO | TODO |
| DocBook | TODO | TODO |
| Texinfo | TODO | TODO |
| Nix EDSL | TODO | TODO |

### Closure sizes of different tools

TODO: Remove this section, as long as tools aren't too big, this isn't relevant or could be showed off in the demos
For the following comparison NixOS 19.09 is used.

| Name | Attribute | Closure size |
|--------------|-----------------------|--------------|
| Sphinx | `python3.pkgs.sphinx` | 195 MB |
| Pandoc | `pandoc` | 2.4 GB |
| Asciidoctor | `asciidoctor` | 1.0 GB (on master: 80% smaller) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So if we used 20.03, Asciidoctor's closure would be 80% smaller?

Copy link
Member

@cole-h cole-h Apr 27, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just for some concrete numbers, I ran nix path-info -Sh $(nix-build -A asciidoctor) on release-20.03, which output the following:

/nix/store/ylb06pz44l6qr9mpr7m9qakc5brvl57a-asciidoctor-2.0.10   320.6M

whereas master output the following:

/nix/store/gbd8nap6fmy078jgijac1m4i8xg72597-asciidoctor-2.0.10   321.3M


## Format Overviews

This section is to be used in the Discourse post, ordered before the poll. For each format it should contain: (in this order)
- A short description (history, where it's used, design goals, selling points)
- A short example of source code for it and links to the demonstrations from above
- Noteworthy advantages/disadvantages
- Links to tutorials, documentation and tooling

### Markdown (CommonMark)

Markdown is probably the most well-known markup language, used for discussions on many websites such as GitHub, StackExchange, Reddit, Bitbucket and more. While the original description of Markdown was ambiguous, in current times [CommonMark](https://commonmark.org/) provides a clear specification for it. Markdown is designed to be easy to read and write. If you don't know it already, just after a [one minute tutorial](https://commonmark.org/help/) you can be productive with it.

Links:
- [The latest CommonMark specification](https://spec.commonmark.org/current/)
- [Pandoc](https://pandoc.org/) can convert from/to Markdown to/from many other formats
- [Sphinx](https://www.sphinx-doc.org/), a popular documentation generator, known for its [readthedocs](https://readthedocs.org/) pages supports Markdown

#### Why CommonMark instead of another Markdown flavor?
- CommonMark is very near to having a 1.0 release for a standardized and unambiguous syntax specification for Markdown
- The popular Sphinx documentation generator [supports CommonMark](https://www.sphinx-doc.org/en/master/usage/markdown.html) (in addition to reStructuredText)
- GitHub's Markdown is [a strict superset of CommonMark](https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/) and they are committed to having full CommonMark conformance

### reStructuredText

[reStructuredText (reST)](https://en.wikipedia.org/wiki/ReStructuredText) is a file
format originally developed as part of the Docutils project for documenting the Python language.
Since then, support was added for reST to Sphinx, a popular tool for documenting (Python) projects, and pandoc.

With Sphinx it is possible to document various languages using the concept of [domains](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html). E.g., if we were to have a format for documenting Nix functions, we could implement a domain in Sphinx, as well as a parser that could parse Nix functions from comments and convert them to the Sphinx domain, as is done currently with the [Nixpkgs library](https://github.com/NixOS/nixpkgs/pull/53055).

Language:
- [Specification](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html)
- [Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
- [Demo](https://docutils.readthedocs.io/en/sphinx-docs/user/rst/demo.html)

Tooling:
- [Sphinx](https://www.sphinx-doc.org/)
- [Docutils](https://docutils.sourceforge.io/)
- [Pandoc](https://pandoc.org/) can convert from/to reST to/from many other formats

Examples of users:
- Python
- Linux kernel
- CMake
- LLVM
- Majority of Python packages
- PowerDNS: ReST with [Sphinx](https://www.sphinx-doc.org/) for
manuals, guides and manpages

### Asciidoc

TODO: Short overview

[Demo](https://github.com/opendevise/asciidoc-samples/blob/master/demo.adoc)

Tooling:
- [Antora](https://antora.org/)
- [Asciidoctor](https://asciidoctor.org/)

### Texinfo

TODO: Short overview

Powerful, interactive and very nice to use (check out `pinfo`), but harder to write.
Copy link
Contributor

@asymmetric asymmetric Apr 27, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we qualify what use means here (if not write)? Is it about the CLI experience?


### Nix EDSL

With a Nix EDSL, linking to options can become trivial and very natural. Users won't have to learn another language either. Docs could also be written directly next to the thing they document with some convenience functions for annotating values with docs.

### Docbook

TODO: Short overview

[Primer](https://docbook.rocks/)

### Overall Comparisons

| Format | Rendered in GitHub | Adoption | Standardized | Goal |
| --- | --- | --- | --- | --- |
| Markdown | Yes | Great among websites | No | Easy to use |
Copy link
Contributor

@asymmetric asymmetric Apr 27, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it not standardized if one follows CommonMark?

See #64 (comment)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If people have to ask "which markdown standard" it's not standardized imo.
Sure, commonmark's the closest thing to "standard markdown" but you'll probably still end up needing extensions on top of that.

This is only a disadvantage if the other formats under discussion don't have that issue of course.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, so we could say that Markdown itself is standardized, but the standard is insufficient for our goals (i.e. it doesn't have cross-references).

| reStructuredText | Yes | Great among tech docs | Yes | Easy to use, customizable |
| Asciidoc | Yes | ? | Yes | Easy to use, customizable |
| Docbook | No | ? | Yes | Semantic structure |

Cheatsheet comparison: http://hyperpolyglot.org/lightweight-markup



## Some links that don't fit anywhere else in the RFC

TODO: Move or remove this section
- Linux kernel, why Sphinx/reStructuredText (2016): https://lwn.net/Articles/692704/
- Why not Markdown: https://mister-gold.pro/posts/en/asciidoc-vs-markdown/

# Drawbacks
[drawbacks]: #drawbacks


# Alternatives
[alternatives]: #alternatives

Not doing anything

# Unresolved questions
[unresolved]: #unresolved-questions

# Future work
[future]: #future-work

- This RFC only determines the doc format, implementing this change needs to be done in the future
- During that process it would be ideal to move the docs closer to the code they document
- Also during that it would be good to revise the docs overall and update them where necessary