RFC: Technology stack

[avivace]

1. Which (markup?) language should we use to write the documentation?
2. Which tool can we use to read the files written in (1) and render them in HTML?

[AntonioND]

Maybe something like this?

https://github.com/Kitware/CMake/blob/master/Help/dev/documentation.rst
https://github.com/Kitware/CMake/tree/master/Help

The good thing about RST is that it is used by several serious projects to write documentation. All we really need are things like tables, images, automatic tables of contents, and cross-document links. Any tool that supports RST should be able to deal with them. We don't even need to decide which conversion tool to use right away, it would be possible to try with a couple of them using the same source files.

[LunarLambda]

I would be in favour of RST, or any markup language that is reasonably close to plain text. This ensures the source text remains readable no matter how it is viewed, and means people don't need any special tools or significant knowledge to make contributions.

I have no particular preference on the exact tools use, as long as they do not form a barrier for potential contributors.

[quentin-dev]

1. I second RST and have no issues with Markdown if someone proposes a tool that does everything we need in md
2. I think Sphinx is a good place to start, I don't really know any other tools to go from RST -> HTML so I'm definitely open to suggestions

[Lokathor]

https://github.com/rust-lang/mdBook makes quite good HTML output from MarkDown.

[Kyrio]

https://www.mkdocs.org is another possibility for MD -> HTML, with client-based search and easy template creation.

[avivace]

I'd go for markdown. We can always switch to RST later (pandoc)

[quentin-dev]

Markdown is good for me too!