Closed avivace closed 2 years ago
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.
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.
https://github.com/rust-lang/mdBook makes quite good HTML output from MarkDown.
https://www.mkdocs.org is another possibility for MD -> HTML, with client-based search and easy template creation.
I'd go for markdown. We can always switch to RST later (pandoc
)
Markdown is good for me too!