Frequently Used Formatting

This page explains some of the most common ways we format and render text across Fezzik documentation. Use these examples together with those in our template to aid your documentation.

How to Use This Page

When you see a feature you wish to use, compare the HTML rendering (how the page looks to you normally, not how the HTML source code is structured) with the corresponding reStructuredText. To see the reStructuredText, simply click View page source on the top right of the page and find the correct section. Please also add any further useful or frequently used formatting commands to this document along the way!

Note

Consider the following examples a quick start tool. For our actual documentation, you should more thoroughly review how reStructuredText and Sphinx work and use markup and commands as intended. We include a list of resources on the Working with the Documentation page.

TODO

  • cross-referencing into our own source code dynamically (must insert the documentation project into the main project?)

Headings

A title is required for every page (i.e. for every new .rst file you insert). At the top of the .rst file, do you see Frequently Used Formatting has a row of * symbols above and below it? This marks it as the title, of which there can only be one on a given page.

You can also create a sub-headline using = symbols below the the text, or a simple headline using - symbols. In all of these cases, the symbols (whether above and below or just below) must span the full line of text. For example:

This is a Sub-Headline

This is a Simple Headline

Text Styling

You can add commented text (that goes unrendered in the HTML output) by using two dots at the beginning of a line, followed by any normal comment.

General Highlighting:

  • Italicised text: Here is some text in italics,
  • Bolded Text: Here is some text in bold,
  • Code Samples: Here is some text rendered as monospaced code

To insert a hyperlink, you do two things:

  1. insert the link with some describing text in to the text
  2. insert the reference link, usually at the bottom of the page (for illustration purposes, we are placing it just below)

To cross reference to another page in this documentation, the linking is even easier. Here we link to the Working with the Documentation page.

Lists & Tables

Lists:

  • a bullet point

  • another bullet point

    … do you see how this text continues over two lines?

  1. a numbered list item with implicit numbers
  2. another item
  1. a numbered list item with explicit numbering starting at any positive integer
  2. a subsequently numbered item that is formatted cleanly despite having more digits

Simple tables:

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

More complex tables (with more styling options):

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 … …  

Snippets

Like in LaTeX, line breaks in the source file are not directly rendered. However, line block formatting renders as written:

| These lines are
| broken just like within
| the source file.

To insert a code sample, use this (note the two colon syntax and the indentation):

You will see no processing here, though
indentation does disappear.

This code sample can spread over multiple lines.

To insert code that is marked up according to a certain style (say, Python’s), you can use:

for dir in dirs:
    dirs_2 = [f for f in os.listdir(os.path.join(origin_path, dir)) if not isfile(os.path.join(origin_path, dir, f))]
    for dir_2 in dirs_2:
        paths.append(os.path.join(origin_path, dir, dir_2))
        short_paths.append(os.path.join(origin_path, dir,))

for p, path in enumerate(paths):
        everything = os.listdir(path)
        if 'configs.pkl' in everything:
            configs = pickle.load(open(os.path.join(path, 'configs.pkl')))
            if configs['model_type'] == 'Tf_LSTM' and configs['stateful'] == True:
                if configs['hidden_state_sizes'] in [[4], [8], [16], [32], [64], [128], [256], [4]*2, [8]*2, [16]*2, [32]*2, [64]*2, [128]*2, [256]*2]:
                    final_paths.append(short_paths[p])

To insert command line code, always use:

For a couple of bash commands, you can use:

cd fezzik-project/
./self-destruct-now

However, it is best to do this by dynamically linking into our actual source code (TODO!!!).

Directives

Directives make the documentation look nice, so use them!

Attention

Take care! You must plug the wire in first!

Note

Hardware is kinda hard, but you learn a lot!

Caution

If you are not nice to the robot, it will not do anything for you. Literally nothing.

Tip

Study electrical engineering on the side if you want to work with hardware!

Important

Stay hydrated while working during the night, otherwise you fall asleep.

Warning

If you teach robots too much, they will take over the world.

Hint

Robots respond better if you feed them cookies.

Error

Nothing will ever work if you ignore error warnings, that’s for sure!

Danger

Danger, Will Robinson!

Figures

To insert figures, use a path relative to the source directory, Images are stored in _static:

_images/fezzik.jpg

This is the caption of the figure (a simple paragraph).