Example

If you can read this, then It is a Fact that Read the docs uses the RST files to build documentation, not the files in the build folder.

^That’s how you title the page

This is an example page made from examples from this Sphinx ReST Guide

Also, this is how you link to pages within the docs: Wiring Guide Fill Fraction

In order to make use of this special feature, each .rst file must have a link established with a header in the form of

. . [space] _ [link name] :

To restate, the link is made with the header, not the file. Thus, links should be named identically to the headers they refer to (spaces are allowed, as demonstrated below).

The first Header of a file should be similar to the name of the file.

Any headings, within a page can be linked to as well.

so long as every link name established is unique, the links work. For headings, let’s use convention primaryHeading_subHeading

Font

(^how to make a heading)

one asterisk: text for emphasis (italics),

two asterisks: text for strong emphasis (boldface), and

backquotes: text for code samples. Also, text

Code:

some.module.name.foo(x)
some.module.name.foo(y, z)

Return a line of text input from the user.

1def my_function():
2  if True
3    for line in doc
4        print(line)

Start ‣ Programs ‣ vDAQ Test Panel

log subscript

e superscript

Since Pythagoras, we know that \(a^2 + b^2 = c^2\).

thisisoneword

spacesare*required*,normally

Lists

  • This is a bulleted list.

  • It has two items, the second item uses two lines.

  1. This is a numbered list.

  2. It has two items too.

  3. This is a numbered list.

  4. It has two items too.

^If you want lists to restart, then number them

  1. This is one

  2. This is two

    This still two

  1. This is one

  2. This is two

Definition lists (ref) are created with indents:

term (up to a line of text)

Definition of the term, which must be indented

and can even consist of multiple paragraphs

This is a quote

you make it by indenting more than the surrounding paragraphs

next term

Description.

Line blocks (pipes) are a way of preserving line breaks:

These lines are
broken exactly like in
the source file.

Field Lists

Date

2001-08-16

Version

1

Authors

  • Me

  • Myself

  • I

Indentation

Since the field marker may be quite long, the second and subsequent lines of the field body do not have to line up with the first line, but they must be indented relative to the field name marker, and they must line up with each other.

Parameter i

integer

Also use it to document functions

fieldname

Field content

def my_function(my_arg, my_other_arg):

A function just for me.

param my_arg

The first of my arguments.

param my_other_arg

The second of my arguments.

returns

A message (just for me, of course).

Option lists

-a

Output all.

-b

Output both (this description is quite long).

-c arg

Output just arg.

--long

Output all day long.

-p

This option has two paragraphs in the description. This is the first.

This is the second. Blank lines may be omitted between options (as above) or left in (as here and below).

--very-long-option

A VMS-style option. Note the adjustment for the required two spaces.

--an-even-longer-option

The description can also start on the next line.

-2, --two

This option has two variants.

-f FILE, --file=FILE

These two options are synonyms; both have arguments.

/V

A VMS/DOS-style option.

Quoted literal blocks

John Doe wrote:

>> Great idea!
>
> Why didn"t I think of that?

You just did! ;-) Syntax diagram:

paragraph (ends with “::”)

“>” per-line-quoted “>” contiguous literal block

Doctest Blocks

This is an ordinary paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

The following is a literal block:

>>> This is not recognized as a doctest block by
reStructuredText.  It *will* be recognized by the doctest
module, though!

Tables

Below is a grid table

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

…

…

Below is a simple table

A

B

A and B

False

False

False

True

False

False

False

True

False

True

True

True

By far, the best way to do it is below:

Title

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

Admonitions

Note

admonition

Hint

admonition

Important

admonition

Tip

admonition

Attention

admonition

Caution

admonition

Warning

admonition

Danger

admonition

Error

admonition

Media

alternate text

RST Text after the image. It is nestled in with the image.

alternate text

This is how you pull a picture from a parent or other directory and put it in a figure

some.module.name.foo(x)
some.module.name.foo(y, z)

Return a line of text input from the user.

Embedding a Youtube video, and also centering it horizontally