Forum | Documentation | Website | Blog

Skip to content
Snippets Groups Projects
Commit a34bc82e authored by Deepak Khatri's avatar Deepak Khatri :dog:
Browse files

Add rationale for using RST to contribution guide

parent 90d64a3b
No related merge requests found
Pipeline #5473 passed with stages
in 18 minutes and 56 seconds
...@@ -3,17 +3,30 @@ ...@@ -3,17 +3,30 @@
ReStructuredText Cheat Sheet ReStructuredText Cheat Sheet
############################ ############################
BeagleBoard.org docs site uses ReStructuredText (rst) which is a file format [#]_ for textual data used primarily `BeagleBoard.org docs site <https://docs.beagleboard.org>`_ uses ReStructuredText (rst) which is a
in the Python programming language community for technical documentation. It is part of the Docutils file format [#]_ for textual data used primarily in the Python programming language community
project of the Python Doc-SIG, aimed at creating a set of tools for Python similar to Javadoc for Java for technical documentation. It is part of the Docutils project of the Python Doc-SIG, aimed at
or Plain Old Documentation for Perl. If you are new with rst you may go through this rst cheat sheet [#]_ [#]_ [#]_ creating a set of tools for Python similar to Javadoc for Java or Plain Old Documentation for
chapter to gain enough skills to edit and update any page on the BeagleBoard.org docs site. some things Perl. If you are new with rst you may go through this rst cheat sheet [#]_ [#]_ [#]_ chapter
to gain enough skills to edit and update any page on the BeagleBoard.org docs site. some things
you should keep in mind while working with rst, you should keep in mind while working with rst,
1. like Python, RST syntax is sensitive to indentation ! 1. like Python, RST syntax is sensitive to indentation !
2. RST requires blank lines between paragraphs 2. RST requires blank lines between paragraphs
.. tip::
Why not use Markdown for documentation? because reST stands out against Markdown as,
1. It's more fully-featured.
2. It's much more standardized and uniform.
3. It has built-in support for extensions.
For more detailed comparison you can checkout `this article on
reStructuredText vs. Markdown for technical documentation
<https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/>`_
Text formatting Text formatting
**************** ****************
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment