Paragraph Level Markup

Inline Markup

Paragraphs contain text and may also contain inline markup, such as:

emphasis, strong emphasis, inline literals, standalone hyperlinks (http://www.python.org), internal cross-references (example_), external hyperlinks with embedded URIs (Python web site), footnote references (manually numbered [1], anonymous auto-numbered [3], labeled auto-numbered [2]), citation references ([12]_), substitution references (|example|), and inline hyperlink targets.

Emphasis:

*text*

Strong emphasis:

**text**

inline literal:

``inline literal``

Standalone hyperlink:

http://www.python.org http://www.python.org

Internal cross-reference:

example_ example_

External hyperlink with embedded URI:

Python web site `Python web site <http://www.python.org>`_

Footnote reference:

• manually numbered [1] [1]_

• anonymous auto-numbered [#]_ [#]_

• labeled auto-numbered [2] [#label]_

Citation reference:

Reference ([12]_) ([12]_)

Substitution reference:

(|example|) (|example|)

inline hyperlink target:

_`inline hyperlink target`

Warning

Invalid hyperlinks will display red_.

GUI labels

GUI labels (:guilabel:`some action`) are a useful way to indicate that Some action is to be taken by the user. The GUI label should not run over line-height so as not to interfere with text from adjacent lines.

Key bindings

Key-bindings (:kbd:`key`) indicate that the read is to press a button on the keyboard or mouse, for example MMB and Shift-MMB.

Menu Selection

Another useful markup to indicate a user action is to use :menuselection:`Path --> To`:

My ‣ Software ‣ Some menu ‣ Some sub menu 1 ‣ sub menu 2.

Math

• Here is an equation formatted with :math:

  :math:`X_{0:5} = (X_0, X_1, X_2, X_3, X_4)`.
  

  \(X_{0:5} = (X_0, X_1, X_2, X_3, X_4)\).

• A more complex example:

  .. math::
  
    \nabla^2 f =
    \frac{1}{r^2} \frac{\partial}{\partial r}
    \left( r^2 \frac{\partial f}{\partial r} \right) +
    \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta}
    \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) +
    \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}
  

  \[\nabla^2 f = \frac{1}{r^2} \frac{\partial}{\partial r} \left( r^2 \frac{\partial f}{\partial r} \right) + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}\]

Note

Math elements have overflow:auto enabled by default.

Blocks

Literal Blocks

Literal blocks are indicated with a double-colon (“::”) at the end of the preceding paragraph. They can be indented.

Title ::

  this is a literal block
      with indentation

Title

this is a literal block
    with indentation

Or they can be quoted without indentation:

>> This is a literal block
> without indentation

Line Blocks

Line blocks end with a blank line, preserving line breaks.

Each new line begins with a vertical bar (“|”).

| Lorem ipsum dolor sit amet,
| consetetur sadipscing elitr,
| sed diam nonumy eirmod tempor invidunt
| ut labore et dolore magna aliquyam

Lorem ipsum dolor sit amet,

consetetur sadipscing elitr,

sed diam nonumy eirmod tempor invidunt

ut labore et dolore magna aliquyam

Block Quotes

Block quotes consist of indented body elements.

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam

References

Footnotes

[1] (1,2,3)

A footnote contains body elements, consistently indented by at least 3 spaces.

This is the second paragraph.

[2] (1,2,3)

Footnotes may be numbered, either manually (as in [1]) or automatically using a “#”-prefixed label. This footnote has a label so it can be referred to from multiple places, both as a footnote reference ([2]) and as a hyperlink reference (label).

[3]

This footnote is numbered automatically and anonymously using a label of “#” only.

.. [1] A simple footnote

   This is the second paragraph.

.. [#label] A numbered footnote with a label.

.. [#] This footnote is numbered automatically and anonymously.

Glossary

This is a glossary with definition terms like Writing:

.. glossary::

   Documentation
      Provides users with the knowledge they need to use something.

   Reading
      The process of taking information into ones mind through the use
      of eyes.

   Writing
      The process of putting thoughts into a medium for other people
      to :term:`read <Reading>`.

Documentation

Provides users with the knowledge they need to use something.

Reading

The process of taking information into ones mind through the use of eyes.

Writing

The process of putting thoughts into a medium for other people to read.

Link to a term with :term:.

:term:`description <Termname>`

Tip

Try clicking on the terms above!

Admonitions

Use admonitions for important information.

.. Info:: This is an example admonition.

Danger

This is an example danger admonition.

.. DANGER::

Attention

This is an example attention admonition.

.. Attention::

Error

This is an example error admonition.

.. Error::

Caution

This is an example caution admonition.

.. Caution::

Warning

This is an example warning admonition

.. WARNING::

Hint

This is an example hint admonition.

.. Hint::

Tip

This is an example tip admonition.

.. Tip::

Important

This is an example important admonition.

.. Important::

Note

This is a note.

.. Note::

This is a custom admonition. Its default color is gray.

.. some-name::

Admonition nesting

Most elements can be nested in an admonition, for example:

Warning

Math elements: \(X_{0:5} = (X_0, X_1, X_2, X_3, X_4)\).

Important

Tables:

Header1	Header2	Header3	Header4	Header5
Content	Content	Content	Content	Content
Content	Content	Content	Content	Content
Content	Content	Content	Content	Content

Tip

Images and Figures:

This is a caption for this image of a fibonacci spiral.

Note

Links:

This is an example download link

Hyperlinks

External links

Use Link text for simple inline web links.

`Link text <https://domain.invalid/>`_

Important

There must be a space between the link text and the opening < for the URL.

You can also separate the link and the target definition.

This is a paragraph that contains a link.

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/

Internal links

Cross-referencing locations:

Place a label directly before the section title.

You can reference to it with :ref:`label-name`.

.. _your-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`your-label`.

Try this hyperlink to download links: Download Links

You can also label a figure.

.. _my-figure:

.. figure:: ./_static/rgb.png
    :width: 180px

    This is an image of rgb color mixing.

This is an image of rgb color mixing.

Reference the figure like so:

:ref:`my-figure`

This is an image of rgb color mixing.

Caution

Reference labels must start with an underscore. When referencing a label, the underscore must be omitted.

Directly link to documents:

:doc:`lists`

Try this link to Lists!

Or add your own link text.

:doc:`Go to lists here </lists>`

Go to lists here

Note

You can also reference tables.

Download Links

This is an example download link

Use download links by prepending :download::

:download:`Title <https://download-link.com>`

On this page