RFC: Technology stack about gbadoc HOT 7 CLOSED

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.

from gbadoc.

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.

from gbadoc.

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

from gbadoc.

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

from gbadoc.

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

from gbadoc.

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

from gbadoc.

Markdown is good for me too!

from gbadoc.