search

gbadev-org / gbadoc

Community initiated GBA Technical documentation effort
http://gbadev-org.github.io/gbadoc/
Creative Commons Zero v1.0 Universal
46 stars 7 forks source link

RFC: Technology stack #2

Closed avivace closed 2 years ago

avivace commented 3 years ago
  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 commented 3 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.

LunarLambda commented 3 years ago

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 commented 3 years ago
  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 commented 3 years ago

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

Kyrio commented 3 years ago

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

avivace commented 3 years ago

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

quentin-dev commented 3 years ago

Markdown is good for me too!