From e5985d63fb2e8cc831f9c1358e3f5582d2773a6f Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 31 Dec 2019 19:56:08 +0100 Subject: [PATCH 01/23] Initial draft --- rfcs/0063-documentation-format.md | 101 ++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 rfcs/0063-documentation-format.md diff --git a/rfcs/0063-documentation-format.md b/rfcs/0063-documentation-format.md new file mode 100644 index 000000000..a0a2e16fd --- /dev/null +++ b/rfcs/0063-documentation-format.md @@ -0,0 +1,101 @@ +--- +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) +related-issues: (will contain links to implementation PRs) +--- + +# Summary +[summary]: #summary + +The Nix community wants to move away from using Docbook as our documentation format and replace it with something else. However it is unclear what it should be replaced with. This RFC gives a concrete process for determining the new documentation format. It does NOT say what format should be used. + +# Motivation +[motivation]: #motivation + +There's been enough bike-shedding over the documentation format to use. We should finally settle this debate by deciding and committing on a single format such that we can move forward and improve our documentation situation. + +# Detailed design +[design]: #detailed-design + +The process for determining the doc format is as follows: +- This RFC is filled out with a good and objective overview of each format with their advantages/disadvantages. This gets refined through the RFC process such that all shepherd members are satisfied with it and the RFC is accepted +- 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 +- Whatever format wins in the poll is chosen as the new default documentation format. If later it is discovered that the winner is infeasible for any reason, the format on second place is chosen instead, and so on. + +## Format overviews + +### Markdown + +TODO: Short overview + +Tooling: +- [Sphinx](https://www.sphinx-doc.org/) + +### reStructuredText + +TODO: Short overview + +[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/) + +### Asciidoc + +TODO: Short overview + +[Demo](https://github.com/opendevise/asciidoc-samples/blob/master/demo.adoc) + +Tooling: +- [Antora](https://antora.org/) +- [Asciidoctor](https://asciidoctor.org/) + +### Docbook + +TODO: Short overview + +[Primer](https://docbook.rocks/) + +### Comparisons + +| Format | Rendered in GitHub | Adoption | Standardized | Goal | +| --- | --- | --- | --- | --- | +| Markdown | Yes | Great among websites | No | Easy to use | +| 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 + +- Linux kernel, why Sphinx/reStructuredText (2016): https://lwn.net/Articles/692704/ + +TODO: More online comparisons? + +## Poll + +The poll is of the following form: +- Multiple-choice, allowing people to select all formats they accept +- Results are only shown when the poll is closed for it to not be influenced by non-final tallies +- It runs for 1 month to give enough time for less-active people to see it +- Who voted for which options is made public (Only possible with bar chart in Discourse) + +# Drawbacks +[drawbacks]: #drawbacks + + +# Alternatives +[alternatives]: #alternatives + + +# Unresolved questions +[unresolved]: #unresolved-questions + + +# Future work +[future]: #future-work + From fba74069d57377ad2ef802db16b2d80a8b775fd3 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Sun, 5 Jan 2020 20:54:52 +0100 Subject: [PATCH 02/23] Move to correct location --- ...{0063-documentation-format.md => 0064-documentation-format.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rfcs/{0063-documentation-format.md => 0064-documentation-format.md} (100%) diff --git a/rfcs/0063-documentation-format.md b/rfcs/0064-documentation-format.md similarity index 100% rename from rfcs/0063-documentation-format.md rename to rfcs/0064-documentation-format.md From cb6929c8b80f8862af7856a2063050b56101ba9f Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Sun, 5 Jan 2020 21:20:40 +0100 Subject: [PATCH 03/23] Move the poll higher up --- rfcs/0064-documentation-format.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index a0a2e16fd..ac892ad8f 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -26,6 +26,14 @@ The process for determining the doc format is as follows: - 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 - Whatever format wins in the poll is chosen as the new default documentation format. If later it is discovered that the winner is infeasible for any reason, the format on second place is chosen instead, and so on. +## Poll + +The poll is of the following form: +- Multiple-choice, allowing people to select all formats they accept +- Results are only shown when the poll is closed for it to not be influenced by non-final tallies +- It runs for 1 month to give enough time for less-active people to see it +- Who voted for which options is made public (Only possible with bar chart in Discourse) + ## Format overviews ### Markdown @@ -76,13 +84,6 @@ Cheatsheet comparison: http://hyperpolyglot.org/lightweight-markup TODO: More online comparisons? -## Poll - -The poll is of the following form: -- Multiple-choice, allowing people to select all formats they accept -- Results are only shown when the poll is closed for it to not be influenced by non-final tallies -- It runs for 1 month to give enough time for less-active people to see it -- Who voted for which options is made public (Only possible with bar chart in Discourse) # Drawbacks [drawbacks]: #drawbacks From 7c4c8a4ae3c3e47181067df473b21ccec2396279 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Sun, 5 Jan 2020 23:31:21 +0100 Subject: [PATCH 04/23] Mention that poll answers can be changed while open --- rfcs/0064-documentation-format.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index ac892ad8f..5d2c2b845 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -31,6 +31,7 @@ The process for determining the doc format is as follows: The poll is of the following form: - Multiple-choice, allowing people to select all formats they accept - Results are only shown when the poll is closed for it to not be influenced by non-final tallies +- Answers can be changed while the poll is still active, allowing people to discuss about formats and change their opinion - It runs for 1 month to give enough time for less-active people to see it - Who voted for which options is made public (Only possible with bar chart in Discourse) From 443698bea6f40839274546a4674117b6ffc8321b Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 6 Jan 2020 05:26:10 +0100 Subject: [PATCH 05/23] Specify CommonMark --- rfcs/0064-documentation-format.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 5d2c2b845..b5bda377b 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -37,13 +37,18 @@ The poll is of the following form: ## Format overviews -### Markdown +### Markdown (CommonMark) TODO: Short overview Tooling: - [Sphinx](https://www.sphinx-doc.org/) +#### 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 TODO: Short overview From 7560aca0f57c4025d45e068a9ebdafa9749e9628 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 6 Jan 2020 05:54:15 +0100 Subject: [PATCH 06/23] Add a short overview of markdown --- rfcs/0064-documentation-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index b5bda377b..050d37815 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -39,7 +39,7 @@ The poll is of the following form: ### Markdown (CommonMark) -TODO: Short overview +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. Tooling: - [Sphinx](https://www.sphinx-doc.org/) From 9df0d02e357b2e106f9509a3927c9f64e1ffe3ba Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 6 Jan 2020 21:48:38 +0100 Subject: [PATCH 07/23] Build requirements into the process, list some requirements --- rfcs/0064-documentation-format.md | 34 +++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 050d37815..33fe81f6c 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -22,18 +22,34 @@ There's been enough bike-shedding over the documentation format to use. We shoul [design]: #detailed-design The process for determining the doc format is as follows: -- This RFC is filled out with a good and objective overview of each format with their advantages/disadvantages. This gets refined through the RFC process such that all shepherd members are satisfied with it and the RFC is accepted -- 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 -- Whatever format wins in the poll is chosen as the new default documentation format. If later it is discovered that the winner is infeasible for any reason, the format on second place is chosen instead, and so on. +- 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. +- A short objective overview of each valid candidate format is written, along with their advantages/disadvantages +- The RFC is accepted +- 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 +- Whatever format wins in the poll is chosen as the new default documentation format. If later it is discovered that the winner is infeasible for any reason, e.g. if it doesn't meet the requirements after all, the format on second place is chosen instead, and so on. ## Poll The poll is of the following form: -- Multiple-choice, allowing people to select all formats they accept +- 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 -- Answers can be changed while the poll is still active, allowing people to discuss about formats and change their opinion +- 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 -- Who voted for which options is made public (Only possible with bar chart in Discourse) +- 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? + +## Requirements + +- Can be converted to HTML and man pages +- Inter-file references for being able to link to options from anywhere +- Ability to create link anchors to most places such that we can link to e.g. paragraphs +- Errors are easily and quickly detectable, e.g. with a fast and good processor, a live-view, or highlighting editor plugins +- Is decently fast to fully generate, in the range of 10 seconds for the full documentation on an average machine + +### Nice-to-have's + +- Annotations/links inside code listings for e.g. linking to option docs in `configuration.nix` snippets +- Ability to make `$ `'s in command line snippets non-copyable ## Format overviews @@ -41,8 +57,10 @@ The poll is of the following form: 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. -Tooling: -- [Sphinx](https://www.sphinx-doc.org/) +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 From b68de43a4ddc7429ec3ef4e6a7f3991693d27f99 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 6 Jan 2020 23:06:54 +0100 Subject: [PATCH 08/23] Add texinfo as a potential candidate --- rfcs/0064-documentation-format.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 33fe81f6c..711ccbf2c 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -87,6 +87,12 @@ 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. + ### Docbook TODO: Short overview From 8c44064636b1cb97ba2daa3086b38e0402f36caa Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 6 Jan 2020 23:46:47 +0100 Subject: [PATCH 09/23] Add Nix EDSL --- rfcs/0064-documentation-format.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 711ccbf2c..e82e4eaea 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -53,6 +53,12 @@ The poll is of the following form: ## Format overviews +Should contain for each format: +- A short description +- Noteworthy advantages/disadvantages +- Links to tutorials, documentation and tooling +- A short sample + ### 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. @@ -93,6 +99,10 @@ TODO: Short overview Powerful, interactive and very nice to use (check out `pinfo`), but harder to write. +### 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 From 1b7c25e22dc177cbc22b1eacd27c28c82b88ee06 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 7 Jan 2020 14:19:18 +0100 Subject: [PATCH 10/23] other prompts non-copyable --- rfcs/0064-documentation-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index e82e4eaea..7ec69ea5d 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -49,7 +49,7 @@ The poll is of the following form: ### Nice-to-have's - Annotations/links inside code listings for e.g. linking to option docs in `configuration.nix` snippets -- Ability to make `$ `'s in command line snippets non-copyable +- Ability to make `$ `, `nix-repl>` and other prompts in command line snippets non-copyable ## Format overviews From 999b91b8b9321dce38eabe306d645172b1146ff0 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 7 Jan 2020 14:30:10 +0100 Subject: [PATCH 11/23] Add some more requirements and an article suggested by @domenkozar --- rfcs/0064-documentation-format.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 7ec69ea5d..9c9982d47 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -43,13 +43,17 @@ The poll is of the following form: - Can be converted to HTML and man pages - Inter-file references for being able to link to options from anywhere - Ability to create link anchors to most places such that we can link to e.g. paragraphs -- Errors are easily and quickly detectable, e.g. with a fast and good processor, a live-view, or highlighting editor plugins +- Errors are easily and quickly detectable, e.g. with a fast and good processor, a live-view, or highlighting editor plugins for most editors - Is decently fast to fully generate, in the range of 10 seconds for the full documentation on an average machine +- Supports syntax highlighting (with Nix support) +- Active community supporting the tooling infrastructure +- Good conversion story from Docbook ### Nice-to-have's - Annotations/links inside code listings for e.g. linking to option docs in `configuration.nix` snippets - Ability to make `$ `, `nix-repl>` and other prompts in command line snippets non-copyable +- Good search feature (better than Ctrl-F) ## Format overviews @@ -121,6 +125,7 @@ TODO: Short overview Cheatsheet comparison: http://hyperpolyglot.org/lightweight-markup - Linux kernel, why Sphinx/reStructuredText (2016): https://lwn.net/Articles/692704/ +- Why not Markdown: https://mister-gold.pro/posts/en/asciidoc-vs-markdown/ TODO: More online comparisons? From 690d9b2474be665b20d186cf53a37e8220aaebbd Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Tue, 7 Jan 2020 19:17:42 +0100 Subject: [PATCH 12/23] rewrite motivation --- rfcs/0064-documentation-format.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 9c9982d47..bd9d1b145 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -16,7 +16,8 @@ The Nix community wants to move away from using Docbook as our documentation for # Motivation [motivation]: #motivation -There's been enough bike-shedding over the documentation format to use. We should finally settle this debate by deciding and committing on a single format such that we can move forward and improve our documentation situation. +The current format for documentation of NixOS projects is DocBook. The format has been a discussion for many years for multiple reasons. +This RFC describes a method for deciding on what format to use, and should allow us to decide on a format for the coming years, and improve our documentation situation. # Detailed design [design]: #detailed-design From ca700a7b9315c11621437f78eb42f7f663286732 Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Tue, 7 Jan 2020 19:24:39 +0100 Subject: [PATCH 13/23] minor changes in requirements --- rfcs/0064-documentation-format.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index bd9d1b145..828f0367e 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -44,8 +44,10 @@ The poll is of the following form: - Can be converted to HTML and man pages - Inter-file references for being able to link to options from anywhere - Ability to create link anchors to most places such that we can link to e.g. paragraphs -- Errors are easily and quickly detectable, e.g. with a fast and good processor, a live-view, or highlighting editor plugins for most editors +- Widespread editor integration featuring at least highlighting and preferably live-view +- 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 +- Closure-size of toolchain should be small. - Supports syntax highlighting (with Nix support) - Active community supporting the tooling infrastructure - Good conversion story from Docbook @@ -54,7 +56,7 @@ The poll is of the following form: - Annotations/links inside code listings for e.g. linking to option docs in `configuration.nix` snippets - Ability to make `$ `, `nix-repl>` and other prompts in command line snippets non-copyable -- Good search feature (better than Ctrl-F) +- Good search integration, e.g. by providing a well-functioning search field ## Format overviews From 7a2626d00041de410a343454efc03b42705f40e2 Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Tue, 7 Jan 2020 19:33:17 +0100 Subject: [PATCH 14/23] Extend restructuredtext section --- rfcs/0064-documentation-format.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 828f0367e..def5e1d03 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -82,13 +82,25 @@ Links: ### reStructuredText -TODO: Short overview +[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. -[Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Demo](https://docutils.readthedocs.io/en/sphinx-docs/user/rst/demo.html) +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 +- Majority of Python packages ### Asciidoc From 1d15ed4e035e3f6e00982b3eadcef5a15029b12c Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Tue, 7 Jan 2020 19:39:50 +0100 Subject: [PATCH 15/23] Add comparison of tools, showing closure size --- rfcs/0064-documentation-format.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index def5e1d03..4167d4bcc 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -144,6 +144,15 @@ Cheatsheet comparison: http://hyperpolyglot.org/lightweight-markup TODO: More online comparisons? +### Comparison of tools + +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 | # Drawbacks [drawbacks]: #drawbacks From 29bd2492d0200cfc7d0341baed9fb3856f3e584c Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Tue, 7 Jan 2020 20:00:35 +0100 Subject: [PATCH 16/23] Describe sphinx domains --- rfcs/0064-documentation-format.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 4167d4bcc..6dfd03b1c 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -86,6 +86,8 @@ Links: 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) From 81bd8ac681303d714c1468869dee4d10f24aeb97 Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Tue, 7 Jan 2020 20:00:47 +0100 Subject: [PATCH 17/23] Refer to closure size ticket --- rfcs/0064-documentation-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 6dfd03b1c..a4dee1064 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -47,7 +47,7 @@ The poll is of the following form: - Widespread editor integration featuring at least highlighting and preferably live-view - 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 -- Closure-size of toolchain should be small. +- 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 From 5ca448d74991f2162a6d585591a3bc5738784a64 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Sat, 11 Jan 2020 02:14:40 +0100 Subject: [PATCH 18/23] Integrate feedback --- rfcs/0064-documentation-format.md | 72 +++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 23 deletions(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index a4dee1064..a1298dbce 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -11,27 +11,31 @@ related-issues: (will contain links to implementation PRs) # Summary [summary]: #summary -The Nix community wants to move away from using Docbook as our documentation format and replace it with something else. However it is unclear what it should be replaced with. This RFC gives a concrete process for determining the new documentation format. It does NOT say what format should be used. +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 format for documentation of NixOS projects is DocBook. The format has been a discussion for many years for multiple reasons. -This RFC describes a method for deciding on what format to use, and should allow us to decide on a format for the coming years, and improve our documentation situation. +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. +- 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 -- The RFC is accepted - 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 -- Whatever format wins in the poll is chosen as the new default documentation format. If later it is discovered that the winner is infeasible for any reason, e.g. if it doesn't meet the requirements after all, the format on second place is chosen instead, and so on. +- Whatever format wins in the poll is chosen as the new default documentation format. This decision is added to the RFC text 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 +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 @@ -51,6 +55,7 @@ The poll is of the following form: - 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 @@ -58,13 +63,38 @@ The poll is of the following form: - 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 -## Format overviews +## 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) | + +## Format Overviews -Should contain for each format: -- A short description +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 -- A short sample ### Markdown (CommonMark) @@ -130,7 +160,7 @@ TODO: Short overview [Primer](https://docbook.rocks/) -### Comparisons +### Overall Comparisons | Format | Rendered in GitHub | Adoption | Standardized | Goal | | --- | --- | --- | --- | --- | @@ -141,20 +171,13 @@ TODO: Short overview Cheatsheet comparison: http://hyperpolyglot.org/lightweight-markup -- Linux kernel, why Sphinx/reStructuredText (2016): https://lwn.net/Articles/692704/ -- Why not Markdown: https://mister-gold.pro/posts/en/asciidoc-vs-markdown/ - -TODO: More online comparisons? -### Comparison of tools -For the following comparison NixOS 19.09 is used. +## Some links that don't fit anywhere else in the RFC -| Name | Attribute | Closure size | -|--------------|-----------------------|--------------| -| Sphinx | `python3.pkgs.sphinx` | 195 MB | -| Pandoc | `pandoc` | 2.4 GB | -| Asciidoctor | `asciidoctor` | 1.0 GB | +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 @@ -163,11 +186,14 @@ For the following comparison NixOS 19.09 is used. # 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 From 3eeeda9773dde24d6223838743da1af82f03832b Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Sat, 11 Jan 2020 02:30:19 +0100 Subject: [PATCH 19/23] shepherds have the final word, only using poll as an input --- rfcs/0064-documentation-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index a1298dbce..0fdde07f0 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -29,7 +29,7 @@ The process for determining the doc format is as follows: - 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 -- Whatever format wins in the poll is chosen as the new default documentation format. This decision is added to the RFC text after which it is merged. +- 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 From 85c173682dc19edcd18f1048eead8994bfa22271 Mon Sep 17 00:00:00 2001 From: energizah <45742652+energizah@users.noreply.github.com> Date: Tue, 25 Feb 2020 19:56:29 -0800 Subject: [PATCH 20/23] Add LLVM as another example for reST --- rfcs/0064-documentation-format.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 0fdde07f0..3d2a0b6ac 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -132,6 +132,7 @@ Examples of users: - Python - Linux kernel - CMake +- LLVM - Majority of Python packages ### Asciidoc From 46fdccce1dc63cd533663301522519ff1cae484a Mon Sep 17 00:00:00 2001 From: Antoine Eiche Date: Mon, 2 Mar 2020 12:07:05 +0100 Subject: [PATCH 21/23] Add PowerDNS as ReST user example It's an interesting example because they are generating a lot of different kind of documentation, including manpages. --- rfcs/0064-documentation-format.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 3d2a0b6ac..6ed3c6c6a 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -134,6 +134,8 @@ Examples of users: - CMake - LLVM - Majority of Python packages +- PowerDNS: ReST with [Sphinx](https://www.sphinx-doc.org/) for + manuals, guides and manpages ### Asciidoc From 25e4a5a00dbc6af73d80e5f7cb7d16e78a800344 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Thu, 23 Apr 2020 21:30:25 +0200 Subject: [PATCH 22/23] Fill in shepherds --- rfcs/0064-documentation-format.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 6ed3c6c6a..70b206c1d 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -3,8 +3,8 @@ 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) +shepherd-team: @domenkozar, @asymmetric, @alyssais, @jtojnar +shepherd-leader: @domenkozar related-issues: (will contain links to implementation PRs) --- From c96efe0a022befd1c000fa35633df7cf1cf30a1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Domen=20Ko=C5=BEar?= Date: Wed, 20 May 2020 11:35:53 +0200 Subject: [PATCH 23/23] Update rfcs/0064-documentation-format.md --- rfcs/0064-documentation-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0064-documentation-format.md b/rfcs/0064-documentation-format.md index 70b206c1d..cfb08d0fe 100644 --- a/rfcs/0064-documentation-format.md +++ b/rfcs/0064-documentation-format.md @@ -46,7 +46,7 @@ The poll is of the following form: ## Requirements - Can be converted to HTML and man pages -- Inter-file references for being able to link to options from anywhere +- Cross-file references for being able to link to options from anywhere - 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 - Good error detection in toolchain and editors, e.g. with a fast and good processor