Choose format and tool(s) for the technical documentation

[mangolang]

It'd be advantageous to use the same tool for documenting the compiler that will later be used for documenting programs written in the language. Some examples:

• Javadoc (doxygen?)
• reStructuredText (Sphinx)
• Markdown

I'm not very knowledgeable on this topic. I feel like Markdown is used more than reStructuredText. Javadoc may be too limited. From reading some information (one, two), it seems the technically superior choice for large documentation efforts is reStructuredText, with which I have good experiences in Python. The Rust book, which I liked, seems to be written in Markdown.

[mverleg]

Kotlin uses Dokka, which seems good for signatures but maybe not for full documentation.

[mverleg]

Thanks to advice from @imma90 !

We compared documentation tools on various criteria:

• Usable for standalone technical documentation and for in-source api documentation.
• An input format that doesn't take much time for programmers to learn, but is expressive enough for documentation writers. Either Markdown (easy, very popular)) or ReStructuredText (expressive, somewhat popular).
• Multiple output formats, including at least html, and preferably an existing free hosting service.
• Ability to be adapted to Mango. Sphinx has been adapted to other languages like Java and javascript. Info.

Based on that, Sphinx was the winner. The current favourite for input format is ReStructuredText, with alternatives being either Markdown, or Markdown+ReStructuredText.

[mverleg]

The docs are currently at https://docs.mangolang.org/en/latest/ but there isn't much. This runs on ReadTheDocs which uses Sphinx/ReStructuredText. It might be moved later for uniform style and no ads.