Documentation Tools¶
Markdown (.md)¶
Markdown is the most widely used markup language and it is often used to format readme files.
Text written in markdown are easy to read and can be easily converted to HTML.
There are different versions of markdown used , and github suggested one is the most popular.
Restructured Text (.rst)¶
reStructuredText is an easy-to-read, plaintext markup syntax and parser system.
When compared reStructuredText is more formalised and powerful than markdown.
It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents.
reStructuredText is designed for extensibility for specific application domains.
When to use markdown and reStructuredText¶
- If you want to write a gist or a single page readme then it is better to use markdown.
- It you want to a write a documentation consisting of many in-line programs and tables then it is better to use reStructuredText.
- So, which one to use ?
- Generally it is - For small documentation use markdown otherwise use reStructuredText.