ReStructuredText Cheat Sheet¶
BeagleBoard.org docs site uses ReStructuredText (rst) which is a file format 1 for textual data used primarily in the Python programming language community for technical documentation. It is part of the Docutils project of the Python Doc-SIG, aimed at creating a set of tools for Python similar to Javadoc for Java or Plain Old Documentation for Perl. If you are new with rst you may go through this rst cheat sheet 2 3 4 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,
like Python, RST syntax is sensitive to indentation !
RST requires blank lines between paragraphs
Why not use Markdown for documentation? because reST stands out against Markdown as,
It’s more fully-featured.
It’s much more standardized and uniform.
It has built-in support for extensions.
For more detailed comparison you can checkout this article on reStructuredText vs. Markdown for technical documentation
With asterisk you can format the text as italic & bold,
Single asterisk (
*emphasis*gives you italic text
Double asterisk (
**strong emphasis**gives you bold text
With backquote character (`) you can format the text as link & inline literal.
With double back quotes before and after text you can easily create
backquote can be found below escape key on most keyboards.
For each document we divide sections with headings and in ReStructuredText we can use matching overline and underline to indicate a heading.
Document heading (H1) use
First heading (H2) use
Second heading (H3) use
Third heading (H4) use
Fourth heading (H5) use
You can include only one (H1)
# in a single documentation page.
Make sure the length of your heading symbol is at least (or more) the at least of the heading text, for example:
incorrect H1 ##### ① correct H1 ############ ②
① Length of heading symbol
# is smaller than the content above.
② Shows the correct way of setting the document title (H1) with
For adding a code snippet you can use tab indentation to start. For more refined code snippet display
we have the
literalinclude directives as shown below.
This the simplest way of adding code snippet in ReStructuredText.
This is python code:: ① ② import numpy as np ③ import math
① Provide title of your code snippet and add
:: after the text.
② Empty line after the title is required for this to work.
③ Start adding your code.
This is python code:
import numpy as np import math
Simple indentation only supports python program highlighting but, with code block you can
specify which language is your code written in.
code-block also provides better readability
and line numbers support you can useas shown below.
.. code-block:: python ① :linenos: ② import numpy as np ③ import math
① Start with adding
② Optionally, you can enable line numbers for your code.
③ Start adding your code.
1import numpy as np 2import math
To include the entire code or a code snippet from a program file you can use this directive.
.. literalinclude:: filename.cpp ① :caption: Example C++ file ② :linenos: ③ :language: C++ ④ :lines: 2, 4-7 ⑤ :lineno-start: 113 ⑥
① Provide the code file destination.
② Provide caption for the code.
③ Enable line numbers.
④ Set programming language.
⑤ Cherry pick some lines from a big program file.
⑥ Instead of starting line number from 1 start it with some other number. It’s useful when you use :lines:, :start-after:, and :end-before:.
We have a plug-in installed that enables annotated code blocks. Below is an example.
.. callout:: ① .. code-block:: python ② import numpy as np # <1> ③ import math # <2> .. annotations:: ④ <1> Comment #1 ⑤ <2> Comment #2 .. annotations:: ① Indent everything under a `callout` ② Create a normal block for what you want to annotate ③ Add ``<number>`` everywhere you want to annotate. Put it under a comment block if you want the code to run when copied directly. ④ Create an `annotations` block to hold your callout comments ⑤ Create an entry, separating each with a blank line and prefixing them with ``<number>``
import numpy as np # ① import math # ②
① Comment #1
② Comment #2
In the example, I inserted the invisible UTF character U+FEFF after the opening
< to avoid it being
interpreted as a callout symbol. Be sure to remove that character if you attempt to copy-and-paste the