2. RestructuredText Tutorial¶

2.1. Section Headings¶

Section Numbers are made by Headings¶

Sphinx Tutorial 2 - Part
########################

List 2.1 - Chapter
******************

Unordered List 2.1.1 - Section
==============================

Heading4 2.1.1.1 - Subsection
-----------------------------

Heading5 2.1.1.1.1 - Subsubsection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Heading6 2.1.1.1.1.1 - paragraph
''''''''''''''''''''''''''''''''

2.2. Inline Formatting¶

italic text *italic text*

bold text **bold text**

inline literal: select *.rdyn file. ``*.rdyn``

A ^i,j A :sup:`i,j`

A _i,j A :sub:`i,j`

GUI Label: Open Model :guilabel:`Open Model`

GUI Menu: File > Open > *.rdyn :menuselection:`File > Open > *.rdyn`

File: *.rdyn :file:`*.rdyn`

Keyboard: ctrl + s :kbd:`ctrl` + :kbd:`s`

.. this is a Comment
.. with another line

.. this is a Comment
   with another line

2.3. List¶

2.3.1. Unordered List¶

Unordered item1
- nested unordered item1
- nested unordered item2
Unordered item2
1. nested ordered item1
2. nested ordered item2

2.3.2. Ordered List¶

Numbers are auto generated
- sub item1
- sub item2
a, b, c ordered
1. nested ordered item1
2. nested ordered item2

2.4. Image¶

this is image.

image inside of the text. rd001 like this.

images in the list

item1
item2
- sub item1

2.5. Table¶

2.5.1. Simple Table¶

Simple Table¶
Inputs		Output
A	B	A or B
False	False	False
True	False	True
False	True	True
True	True	True

.. table:: Simple Table
   :name: simpletable

   =====  =====  ======
      Inputs     Output
   ------------  ------
   A      B      A or B
   =====  =====  ======
   False  False  False
   True   False  True
   False  True   True
   True   True   True
   =====  =====  ======

2.5.2. Grid Table¶

Grid Table¶
Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4	Cells may span rows.	Cells contain blocks.

.. table:: Grid Table
   :name: gridtable

   +------------+------------+-----------+
   | Header 1   | Header 2   | Header 3  |
   +============+============+===========+
   | body row 1 | column 2   | column 3  |
   +------------+------------+-----------+
   | body row 2 | Cells may span columns.|
   +------------+------------+-----------+
   | body row 3 | Cells may  | - Cells   |
   +------------+ span rows. | - contain |
   | body row 4 |            | - blocks. |
   +------------+------------+-----------+

2.5.3. List Table¶

List Table¶
Heading row 1, column 1	Heading row 1, column 2	Heading row 1, column 3
Row 1, column 1		Row 1, column 3
Row 2, column 1	Row 2, column 2	Row 2, column 3

.. list-table:: List Table
   :header-rows: 1
   :name: table2
   :widths: 25 25 50

   * - Heading row 1, column 1
   - Heading row 1, column 2
   - Heading row 1, column 3
   * - Row 1, column 1
   -
   - Row 1, column 3
   * - Row 2, column 1
   - Row 2, column 2
   - Row 2, column 3

2.5.4. CSV Table¶

csv table without file¶
Header1	Header2	Header3
1	2	3
1, 2	2, 3, 4	3, 4
1, 2	2, 3	3, 4

.. csv-table:: csv table without file
   :name: table3

   Header1, Header2, Header3
   1,2,3
   "1, 2", "2, 3, 4", "3, 4"
   "1, 2", "2, 3", "3, 4"

2.6. Target and Links¶

2.6.1. Internal Links (Anchor)¶

Tutorial_Sphinx/Tutorial_Sphinx:Target and Links

Tutorial_Sphinx/Tutorial_Sphinx:Internal Links (Anchor)

:ref:`Target and Links`
:ref:`Internal Links (Anchor)`

.. _RST Overview:

Overview
**********

RST Overview content

.. _Sphinx Overview:

Overview
*********

Sphinx Overview content

This is a link to the RST Overview: :ref:`RST Overview`

This is a link to the Sphinx Overview: :ref:`Sphinx Overview`

2.6.2. External Links¶

FunctionBay

`FunctionBay <http://www.functionbay.co.kr>`_

RecurDyn homepage is RecurDyn.

RecurDyn homepage is RecurDyn_.

.. _RecurDyn: http://www.recurdyn.com

2.6.3. Footnote¶

auto numbered footnotes

footnotes1 1 and footnotes2 2

1: A footnote1
2: A footnote2

footnotes1 [#f1]_ and footnotes2 [#f2]_

.. [#f1] A footnote1
.. [#F2] A footnote2

2.6.4. Citation¶

Look Reference [Ref] and this [paper1].

Ref: Book or article reference, URL or whatever.
paper1: A global citation

2.7. Code Block¶

C# code¶

var i = 1;
var str = $"test{i}";

C# with line number¶

var i = 1;
var str = $"test{i}";

2.8. Admonition¶

Attention

this is attention.

Caution

This is caution.

Danger

This is danger.

Error

This is error.

Hint

This is hint.

Important

This is important

Note

this is a note text. Use a note for information you want the user to pay particular attention to.

2.9. Glossary¶

2.9.1. Create a glossary¶

Sphinx¶: Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages.
Sublime Text¶: Sublime Text is a sophisticated text editor for code, markup and prose. You’ll love the slick user interface, extraordinary features and amazing performance.

2.9.2. Link a term to glossary entry¶

Sphinx

:term:`Sphinx`

3. Sphinx Tutorial¶

3.1. Figure¶

3.1.1. Figure Number¶

Figure Numbers are auto generated.

Figue 3a, Figure 3b is not supported.

figure number is created automatically.¶

Figure in the list

item1

figure example¶
item2
- sub item
  
  figure example¶

3.1.2. Figure Reference¶

See figure001 :numref:`figure001`

See figure002 :numref:`figure002`

3.2. Table Reference¶

See gridtable :numref:`gridtable`

See listtable :numref:`listtable`

3.3. Math¶

3.3.1. Basics¶

This is an inline equation embedded \(a^2 + b^2 = c^2\) in text.

This is an inline equation embedded :math:`a^2 + b^2 = c^2` in text.

Equation automatic numbering

(1)¶\[a^2 + b^2 = c^2\]

.. math:: a^2 + b^2 = c^2
   :label: eq1

multi line equation

(2)¶\[\begin{split} \begin{aligned} & \mathbf{F}(s)\mathbf{A}(s)=\mathbf{S}(s) \\ & \mathbf{F}(s)=\mathbf{S}(s){{\mathbf{A}}^{-1}}(s) \\ \end{aligned}\end{split}\]

(3)¶\[\begin{split}\begin{aligned} & \mathbf{F}(s)\mathbf{A}(s)=\mathbf{S}(s) \\ & \mathbf{F}(s)=\mathbf{S}(s){{\mathbf{A}}^{-1}}(s) \\ \end{aligned}\end{split}\]

.. math::
:label: 20_tsg_eq001_01

   \begin{aligned}
      & \mathbf{F}(s)\mathbf{A}(s)=\mathbf{S}(s) \\
      & \mathbf{F}(s)=\mathbf{S}(s){{\mathbf{A}}^{-1}}(s) \\
   \end{aligned}

.. math:: \begin{aligned}   & \mathbf{F}(s)\mathbf{A}(s)=\mathbf{S}(s) \\    & \mathbf{F}(s)=\mathbf{S}(s){{\mathbf{A}}^{-1}}(s) \\       \end{aligned}
   :label: 20_tsg_eq001_02

3.3.2. Math in the list¶

(4)¶\[a^2 + b^2 = c^2\]

equation1

(5)¶\[a^2 + b^2 = c^2\]
equation2
- nested equation
  (6)¶\[a^2 + b^2 = c^2\]

3.3.3. Equation Number¶

Use :label: in math expresstion

(7)¶\[A _i ^j\]

.. math::
   :label: myeq_label

   A _i ^j

3.3.4. Math Reference¶

See (7) :eq:`myeq_label`

See (1)

3.3.5. Math Macro¶

3.3.5.1. Inline math Using replace¶

\(\mathbf{F}(s)\) and \({{\mathbf{F}}^{-1}}(s)\)

.. |eq0| replace:: :math:`\mathbf{F}(s)`
.. |eq2| replace:: :math:`{{\mathbf{F}}^{-1}}(s)`

..    |eq0| and and |eq2|

3.3.5.2. Using mathmacro¶

|eq12| and |eq13| and |20_tsg_eq001|

(8)¶\[\eq12 and \eq13\]

.. |eq12| mathmacro:: \mathbf{A}(s)
.. |eq13| mathmacro:: \mathbf{S}(s)

..    |eq12| and |eq13|

.. math:: \eq12 and \eq13
   :label: eq11

3.4. Table of Contents Tree¶

Section Numbers are auto created.

Table of Content¶

.. toctree::
   :numbered:
   :maxdepth: 5

   index
   Tutorial_Sphinx\Tutorial_Sphinx

3.5. Themes¶

https://sphinx-themes.org/

40+ themes

3.5.1. shpinx_rtd_theme¶

Blender

fluiddyn

MIT General Circulation Model

3.5.2. Custom Theme¶

Adobe Acrobat

Mongo DB

SciPy

3.6. Output¶

Html (.html)

HtmlHelp (.hhp)

PDF

ePub

3.7. Reference¶

Sphinx-doc

Sphinx-theme

Sphinx-rtd-theme

RestructuredText CheatSheet

Sphinx CheatSheet