Formatting Guide¶

The standard reST inline markup is quite simple: use

one asterisk: *text* for emphasis (italics): text
two asterisks: **text** for strong emphasis (boldface): text, and
backquotes: `text` for code samples: text

H1 (minus sings) ——–¶

H2 (equal signs) ========¶

H3 (tilde signs) ~~~~~~~~¶

H4 (plus signs) ++++++++¶

Normal text

Tables¶

Draw the cell grid:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	…	…

Let Sphinx figure it out. Easier, but limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

My preferred option: CSV tables

.. csv-table::
    :header: One , two, Tres
    :widths: auto

    Content in column 1, I can even add a `Link <https://google.com>`_, Yolo
    foo, *bar*, **baz**
    Multi-line, This text just goes on and on and on and on and on and on and on and on and on and on and on and on and on and just won't stop, Just keep it short
    What about commas?, "If the cell has text with a comma in it, use quotes", So easy

One	two	Tres
Content in column 1	I can even add a Link	Yolo
foo	bar	baz
Multi-line	This text just goes on and on and on and on and on and on and on and on and on and on and on and on and on and just won’t stop	Just keep it short
What about commas?	If the cell has text with a comma in it, use quotes	So easy

More complete table docs

Tabs¶

Basic Tabs¶

Basic tabs can be coded as follows:

.. tabs::

   .. tab:: Apples

      Apples are green, or sometimes red.

   .. tab:: Pears

      Pears are green.

   .. tab:: Oranges

      Oranges are orange.

Apples are green, or sometimes red.

Pears are green.

Oranges are orange.

Grouped Tabs¶

Tabs can be grouped, so that changing the current tab in one area changes the current tab in the another area. For example:

.. tabs::

   .. group-tab:: Linux

      Linux Line 1

   .. group-tab:: Mac OSX

      Mac OSX Line 1

   .. group-tab:: Windows

      Windows Line 1

.. tabs::

   .. group-tab:: Linux

      Linux Line 1

   .. group-tab:: Mac OSX

      Mac OSX Line 1

   .. group-tab:: Windows

      Windows Line 1

Linux Line 1

Mac OSX Line 1

Windows Line 1

Linux Line 1

Mac OSX Line 1

Windows Line 1

Code Tabs¶

Tabs containing code areas with syntax highlighting can be created as follows:

.. tabs::

   .. code-tab:: c

         int main(const int argc, const char **argv) {
           return 0;
         }

   .. code-tab:: c++

         int main(const int argc, const char **argv) {
           return 0;
         }

   .. code-tab:: py

         def main():
             return

   .. code-tab:: java

         class Main {
             public static void main(String[] args) {
             }
         }

   .. code-tab:: julia

         function main()
         end

   .. code-tab:: fortran

         PROGRAM main
         END PROGRAM main

int main(const int argc, const char **argv) {
  return 0;
}

int main(const int argc, const char **argv) {
  return 0;
}

def main():
    return

class Main {
    public static void main(String[] args) {
    }
}

function main()
end

PROGRAM main
END PROGRAM main

Callouts aka Admonitions¶

Adding notes (text is highlighted in a blue banner):

.. note:: This is a note

Note

This is a note

The directive Types are: “attention”, “caution”, “danger”, “error”, “hint”, “important”, “note”, “tip”, “warning”, “admonition” (latter is generic). To highlight restrictions we should use warning or attention as the text appears in an orange banner.

Attention

Warning

Caution

Danger

Error

Hint

Important

Tip

And if you want to get really creative…

.. admonition:: And, by the way...

   You can make up your own admonition too.

And, by the way…

You can make up your own admonition too.

Includes¶

To include a consitent footer at the end of a page, e.g. to remind readers to provide feedback, create a .txtfile, e.g letusknow.txt with the content (it can include reStructuredText directives). At the bottom of the page you want to add the footer to, use this:

.. include:: letusknow.txt

Metadata¶

To add meta data to a page (great for SEO) add this to the top of the page:

.. meta::
   :description: My Page Description
   :keywords: AppOptics, libarto, AppOpticsne

Exclude from TOC¶

To hide an article from the TOC and not have the make command generate an error use the

:orphan:

directive at the top of the file (as used for this article).