reStructuredtext

date: 2022-05-19 19:48:14

Covering most common stuff

Sphinx documentation contents — Sphinx documentation (sphinx-doc.org)

To introduce different sections in the left navigation bar of the index.html, change the toctree in index.rst as below. Here we have 2 different folders Options and Guidelines.

.. pyradnotes documentation master file, created by
   sphinx-quickstart on Wed May 18 14:53:47 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to pyradnotes's documentation!
======================================

A Tour of Life (This is a short description)

Pyrad

.. toctree::
   :maxdepth: 1
   :caption: Options:

   Options/justlogic
   Options/justcode
   Options/justhardware
   Options/hardwareandcode

.. toctree::
   :maxdepth: 1
   :caption: Guidelines:

   Guidelines/content
   Guidelines/workflow

Syntax

Here is a reference cheat sheet https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst

Text formatting

.. emphasis, and include multiple words
*emphasis*

.. strong emphasis, and include multiple words
**strong emphasis**

.. Note that you can't place 3 aterisks to get the effect of Italic + bold

.. inline literal (code)
``inline literal``

.. The rendering and meaning of interpreted text is domain- or application-dependent.
`interpreted text`

..

Lists Bulleted, Numbered, and Multi-level

.. list without numbers
* ListItem 1
* ListItem 2
* ListItem 3

.. list which have emphasis, Italic, ...
* **ListItem** 1
* *ListItem* 2
* ``ListItem`` 3

.. Numbered list
#. ListItem 1
#. ListItem 2
#. ListItem 3

.. Levels
* ListItem 1
	* indented item
* ListItem 2
	* indented item
* ListItem 3
	* indented item

Admonitions (警告)

4 callouts: Green, blue, yellow and red

.. caution callout (yellow). Note you have to indent each line in this callout
.. caution:: 
    This is a caution paragraph,
    and you should notice this.
    * caution item 0
    * caution item 1

.. danger callout (red)
.. danger:: 
    This is a danger paragraph,
    and you should do something for this.
    * TODO item 0
    * TODO item 1

.. tip callout (green)
.. tip:: 
    This is a tip paragraph,
    and you could refer to this.
    * TIp item 0
    * Tip item 1

.. note caution (blue)
.. note:: 
    This is a note paragraph,
    something to keep in mind.
    * note item 0
    * note item 1

Images

.. Insert a picture from a folder 
   starting from the root of this project
.. image:: /Images/airplane.png


.. Insert a picture from current folder
.. image:: google.png

Code blocks

If the code in your file are all belong to a same programming language, you could set this in conf.py to indicate this as below.

# in conf.py
highlight_language = 'tcl'

2 ways to specify code blocks

.. Insert a code block, note that all
   lines should be indented, and the
   code block should start from the 2nd
   line, and leave the 1st line empty
Here is a python function code sampe::

    def ByteToMega(v):
	    m = v / 1024 / 1024
	    print("%.3f GB" % m)


.. To indicate a specific language syntax
   highlighting. Still, pay attention to 
   the blank lines, and each line of the
   code block should be indented
Here is a tcl function code sample

.. code:: tcl

    proc isDesiredContext { m } {
        set res 0
        if { $m eq "Red-black tree" } {
            set res 1
        }
        return $res
    }

Tables

4 ways to render

  • equal signs, single space to separate different columns

================ =============== ===== ===========
Platform         Self-Contained? Cost  Flexibility
================ =============== ===== ===========
Raspberry        No              $30   Limitless
Lego Mindstorms  Yes             $350  Medium
================ =============== ===== ===========

  • Use table block, you can specify a table name. Note that a new empty line is needed before starting the table

.. table:: MyOptions

    ================ =============== ===== ===========
    Platform         Self-Contained? Cost  Flexibility
    ================ =============== ===== ===========
    Raspberry        No              $30   Limitless
    Lego Mindstorms  Yes             $350  Medium
    ================ =============== ===== ===========

  • Draw all table cells… (en.. interesting… while I’d prefer not to do so)

+----------------+---------------+-----+-----------+
|Platform        |Self-          |     |           |
|                |Contained?     |Cost |Flexibility|
+================+===============+=====+===========+
|Raspberry       |No             |$30  |Limitless  |
+----------------+---------------+-----+-----------+
|Lego Mindstorms |Yes            |$350 |Medium     |
+----------------+---------------+-----+-----------+

  • Use list-table block

    .. list-table:: Comparison
    :widths: 20 10 10 15
    :header-rows: 1

    * - Platform
      - Self-Contained?
      - Cost
      - Flexibility
    * - Raspberry Pi
      - No
      - $30
      - Limitless
    * - Lego Mindstorms
      - Yes
      - $350
      - Medium

  • Use csv-table block

    .. csv-table:: Comparison
    :header: Platform, Self-Contained?, Cost, Flexibility
    :widths: 15 10 30 30

    Raspberry, No, $30, Limitless
    Lego Mindstorms, Yes, $350, Medium