reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

Table of Contents

Intro

Collections

Elements

Etc.

rubric

If you want a section-like element that doesn’t make up the table of contents, consider rubric. Is not actually a section, only looks like a minor section to the readers.

Rubric is simple

Rubric title is typed right after rubric:: (note the space after ::).

1excepteur excepteur Lorem exercitation do.
2
3.. rubric:: Rubric looks like a minor section title
4
5Cillum nulla fugiat dolor consectetur voluptate dolore officia ea sint ipsum.
6
7.. rubric:: But don't make up the table of contents
8
9Minim culpa aliqua culpa deserunt sint fugiat et.

excepteur excepteur Lorem exercitation do.

Rubric looks like a minor section title

Cillum nulla fugiat dolor consectetur voluptate dolore officia ea sint ipsum.

But don’t make up the table of contents

Minim culpa aliqua culpa deserunt sint fugiat et.

Rubric or strong emphasis?

strong emphasis looks often almost as the rubric, but it should appear only within the running text. For section-like titles, choose rubric or, minor level section.

1**Strong-emphasis** looks often almost as the rubric, but it should appear only within the running text.
2
3.. rubric:: For section-like titles, choose rubric
4
5or, minor level section.

Strong-emphasis looks often almost as the rubric, but it should appear only within the running text.

For section-like titles, choose rubric

or, minor level section.

Rubric or minor level section?

Minor level sections looks often almost as the rubric. Many tech writers prefer sections are more meaningful. They also provide easy navigation, because they make up the table of contents.

For example instead

1.. rubric:: Hidden files
2
3   Linux doesn't have hidden files. There is only convention that...

you might use minor section

1Hidden files
2^^^^^^^^^^^^
3
4Linux doesn't have hidden files. There is only convention that...

:orphan:

################################
Minor section vs. rubric example
################################

Here, we test 6 section levels and the rubric.

**********
Section L2
**********

.. rubric:: Rubric title

Section L3
==========

.. rubric:: Rubric title

Section L4
----------

.. rubric:: Rubric title

Section L5
^^^^^^^^^^

.. rubric:: Rubric title

Section L6
''''''''''

.. rubric:: Rubric title

open example

Previous: parsed-literal-block | Next: section

On this page