Functionality in RST and AguaClara Convention

This file will explain how to use RST functionality including images, tables, code, equations, and both internal and cross-document refereces. Additionally, this document is intended to define convention for this textbook project. Any syntax included in this document should be used when contributing to the textbook project. If you come across a function for which there is no convention, please edit this file to include it here.

How to use this file:

Open the source code of the file next to the rendered code. The source code is found by clicking “View page source” at the top of the page. Follow along with the source code and rendered code, using the source code as a reference for the proper syntax.

You will often see this format .. word::. The ‘word’ in this case is called a directive. Directives are what RST uses to format text. Directives allow the inclusion of figures, math, tables, references, color, and much more.

Important

Proper indentation and line spacing is extremely important when writing in RST

Code

You can write code in-line or as a code block. There are two ways of doing each. For in-line code, use ``this syntax`` or :code:`this syntax`. For code blocks, use this syntax:

.. code::

  This is my code block.

Or this syntax:

This text is not a code block, the code block is below::

  This is my code block.

Headings

Headings are defined by an underline consisting of one of the following characters: *,  =,  -,  ^, and ". RST does not give any particular character hierarchy over another for defining titles, sections, subsections, or so on. The user indicates character hierarchy for headings and can use whatever order they want, and the order can change between documents. However, it is better to stick to the same convention throughout a project. This is the convention for the AguaClara textbook:

  • * with overline, for document titles
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • “, for subsubsubsections

Each title, section and subsection should have a label before it, formatted like this .. _headings:. There should always be a blank line between the label and the actual heading, else references to the label will not work. For the sake of document readability, include 3 blank lines before the section label and 2 blank lines before the subsection label. Lesser headings (subsubsections and beyond) do not need to have labels, and there should be one blank line between lower headings and the preceeding content. Here is an example. Note the amount and location of blank lines:

.. _example_document_title:

****************
Document Title
****************
Words go here



.. _example_section:

Section
=========
Words also go here


.. _example_subsection:

Subsection
------------
and here

Subsubsection
^^^^^^^^^^^^^^
Even more words

Two rules:

  • If under and overline are used, their length must be identical
  • The length of the underline must be at least as long as the title itself

Figures

Every figure should have a label, alternative text, and a caption. The label is used to reference a figure and is written before the figure directive. Below, the two figures are labelled fluffy_cat and mountain_figure. The alternative text is a very short desciption of the figure. A caption is written below all of the figure specifications, with a blank line to separate the specs from the caption.

Use the following syntax for including figures from online sources:

.. _fluffy_cat:
.. figure:: https://www.catster.com/wp-content/uploads/2017/08/A-fluffy-cat-looking-funny-surprised-or-concerned.jpg
    :width: 200px
    :align: center
    :height: 100px
    :alt: external figure

    This is a caption.

Use this syntax for figures located within the /Textbook repository on GitHub:

.. _mountain_figure:
.. figure:: mountain.jpg
    :width: 300px
    :align: center
    :alt: internal figure

    Here is a figure labeled ``mountain``. Specify the figure location with folder/image.jpg.
    The base directory for figure location is the directory of the file you are writing.
    In this case, that is Textbook/Textbook_Creation_Help.

Displayed below are the two figures generated using the code above.

external figure

Fig. 1 This is a caption.

internal figure

Fig. 2 Here is a figure labeled mountain. Specify the figure location with folder/image.jpg. The base directory for figure location is the directory of the file you are writing. In this case, that is Textbook/Textbook_Creation_Help.

Math and Equations

Math is very cool, and works natively in RST using LaTeX math syntax. In-line math can be written with the following syntax: :math:`y = ax^2 + bx + c` which displays \(y = ax^2 + bx + c\). To display equations in their own line, use the following syntax:

.. math::
  :label: quadratic

    y = ax^2 + bx + c

Which displays as:

(1)\[ y = ax^2 + bx + c\]

Complex equations can be generated as well, since RST uses LaTeX math.

(2)\[n_{\rm{offset}} = \sum_{k=0}^{N-1} \frac{s_k}{n_k} \ln \left( \frac{k}{k!} \right)\]

When introducing a new equation, Make sure to specify what the parameters in the equation mean. Once the equation has been introduced, its parameters do not need to be explained when displayed in the future. Use the following syntax for introducing equations:

.. math::
  :label: continuity_equation

    \bar v_1 \frac{\pi D_1^2}{4} = \bar v_2 \frac{\pi D_2^2}{4}

| Such that:
| :math:`Q =` fluid flow rate
| :math:`\bar v =` fluid average velocity
| :math:`A =` pipe area
| :math:`r =` pipe radius
| :math:`D =` pipe diameter

All equations that appear on their own are automatically numbered. If you wish to call an equation in a later section of the document or in another document, give it a label. In the example equation above, the label is given with the :label: continuity_equation line. The equation below uses the code from the block above.

(3)\[ \bar v_1 \frac{\pi D_1^2}{4} = \bar v_2 \frac{\pi D_2^2}{4}\]
Such that:
\(Q =\) fluid flow rate
\(\bar v =\) fluid average velocity
\(A =\) pipe area
\(r =\) pipe radius
\(D =\) pipe diameter

Tables

Tables should be made using csv for compatibility with excel:

.. _an_example_table:
.. csv-table:: a title
   :header: "name", "firstname", "age"
   :widths: 20, 20, 10
   :align: center

   "Smith", "John", 40
   "Smith", "John, Junior", 20

The code block above generates the following table:

Table 1 This table has a title
name firstname age
Smith John 40
Smith John, Junior 20

Every table should have a label, shown above as an_example_table

Python and Doctests

  • Test some python code with doctests. To test the code, run make doctest as described here. In the linked document, there are many more options for controlling doctest behavior.

    >>> python="code"
>>> print(5+14)
19

  • You can even print and test tables in doctests:

    >>> import pandas as pd
>>> names_male = pd.Series(['Obama', 'Monroe', 'Jack'])
>>> names_female = pd.Series(['Michelle', 'Juanita', 'Jill'])
>>> var_names = dict( female_names = names_female, male_names = names_male)
>>> df = pd.DataFrame(var_names)
>>> print(df)
  female_names male_names
0     Michelle      Obama
1      Juanita     Monroe
2         Jill       Jack

  • To get doctests to pass through Travis, you’ll have to add any packages you use to the install step in “.travis.yml”. Under install, add a line that says pip install my_package==0.0.0. When doing this, make sure to specify the version as functionality can change!

Assorted Other Convention

  • Colored text. Add colors/styles by using roles defined in /conf.py and /_static/css/custom.css.