- EDIT
- 3. RST Guide
- 3.2 Basic Syntax
Basic Syntax¶
- Author
Aplus Team
- Last-modified
11.11.2021
- Main questions:
What is the basic syntax of RST?
- Topics:
In this section, we will talk about:
- Requirements:
You only need basic computing and programming skills, prior knowledge about markup languages might be beneficial.
A basic environment set-up, as detailed in Module 2.
Prior knowledge of RST, as detailed in Chapter 3.1.
- Estimated working time:
40 min.
Introduction¶
In order to start authoring a course in A+, you should initiate with the most basic RST directives and roles. This chapter will provide you with the fundamentals of RST. All the directives and roles presented in this chapter will give you the necessary skills to create static course content. Most advanced course content will be covered in the modules questionnaires, programming exercises, Acos exercises, Rubyric (manual assessment with rubrics), active elements and points of interest of this manual.
Hint
Remember the following syntax rules while creating an RST document.
RST is sensitive to indentation.
RST requires blank lines between paragraphs and between directives.
RST directives and roles are case-insensitive.
Structural elements¶
In RST as in many other markup languages, the use of structural components is essential to
organise the content within documents. When we talk about RST, sections are not created with a
particular role or directive, as is the case in HTML, where you have the <section> tag. Instead,
in RST, we use titles and transitions to represent sections. Therefore, we strongly suggest
the use of these structural elements to facilitate the reading and understanding of your educational
material. Using titles or headers will also allow the course to be more accessible to users who use
navigation tools and assistive technologies such as screen readers.
Titles¶
Titles in RST are marked with "underlines". When creating your course, it is recommended to use a maximum of three titles within your document (Title, subtitle and subsubtitle). However, if you need to add more, it is completely possible, but not recommend. It is also important to remember that the titles should be descriptive, concise, should not contain cross-references and you should not have jumps in levels (For example, from level one to level 3).
Warning
If under and overline are used, their length must be identical. However, we suggest avoiding the use of overlines.
The length of the underline must be at least as long as the title itself.
Normally, there are no title levels assigned to certain characters. Instead, the levels of headings
are determined by the order in which the underline characters are used. It means that the first
underline characters encountered in the document will be the outermost title (equivalent to a
<h1> title in HTML), the second underline characters will be indicated subtitles (equivalent to
a <h2> title in HTML), and so on.
It is also important to know that each title automatically generates a hyperlink target. The text of the hyperlink target (reference name) is the title itself, but the whitespace between words are replaced by hyphens. We will see more about this in the Links section.
Title syntax consists of underline adornments. All the adornments should remain consistent throughout your chapters. Therefore, you should use the adornments following the order suggested in the table below.
Symbol |
Semantic |
|---|---|
|
Title of the chapter. You should have just one Title per chapter. |
|
Subtitle |
|
Subsubtitle |
|
Subsubsubtitle. We do not recommend using deeper level of headings. |
Code example
input: RST
Chapter Title
==============
Section title
-------------
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada nulla ut eleifend placerat.
Curabitur sit amet nibh convallis, facilisis.
Section subtitle
................
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada nulla ut eleifend placerat.
Curabitur sit amet nibh convallis, facilisis.
Section subsubtitle
'''''''''''''''''''
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada nulla ut eleifend placerat.
Curabitur sit amet nibh convallis, facilisis.
rendered: HTML
Chapter Title
Section title
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada nulla ut eleifend placerat. Curabitur sit amet nibh convallis, facilisis.
Section subtitle
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada nulla ut eleifend placerat. Curabitur sit amet nibh convallis, facilisis.
Section subsubtitle
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada nulla ut eleifend placerat. Curabitur sit amet nibh convallis, facilisis.
Transitions (Horizontal rulers)¶
In addition to titles, it is possible to use transitions (horizontal rulers/lines) to add a visual cue of the sections of your document. However, it is always advisable to use the titles as the primary mechanism for sectioning your documents, as screen readers may not understand the purpose of the transitions.
Warning
Horizontal ruler should not be placed at the beginning or at the end of your document.
Horizontal rulers should not have any indentation..
Horizontal rules required blank lines above and below.
Horizontal rules syntax consists of four consecutive colons ::::. The four colons
should be surrounded by blank lines.
Code example
input: RST
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis vulputate
felis vel bibendum dignissim. Nunc et pretium lacus. Phasellus lorem
tortor, suscipit sed aliquet sit amet, tempor sit amet purus. Cras
efficitur fermentum tellus sit amet aliquam. Aliquam sed turpis faucibus,
aliquam augue ut, nmalesuada orci. Nunc ultricies malesuada risus
scelerisque tristique. Mauris scelerisque nisl purus, id lobortis velit
facilisis a.
::::
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis vulputate
felis vel bibendum dignissim. Nunc et pretium lacus. Phasellus lorem
tortor, suscipit sed aliquet sit amet, tempor sit amet purus. Cras
efficitur fermentum tellus sit amet aliquam. Aliquam sed turpis faucibus,
aliquam augue ut, malesuada orci. Nunc ultricies malesuada risus
scelerisque tristique. Mauris scelerisque nisl purus, id lobortis velit
facilisis a.
rendered: HTML
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis vulputate felis vel bibendum dignissim. Nunc et pretium lacus. Phasellus lorem tortor, suscipit sed aliquet sit amet, tempor sit amet purus. Cras efficitur fermentum tellus sit amet aliquam. Aliquam sed turpis faucibus, aliquam augue ut, malesuada orci. Nunc ultricies malesuada risus scelerisque tristique. Mauris scelerisque nisl purus, id lobortis velit facilisis a.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis vulputate felis vel bibendum dignissim. Nunc et pretium lacus. Phasellus lorem tortor, suscipit sed aliquet sit amet, tempor sit amet purus. Cras efficitur fermentum tellus sit amet aliquam. Aliquam sed turpis faucibus, aliquam augue ut, malesuada orci. Nunc ultricies malesuada risus scelerisque tristique. Mauris scelerisque nisl purus, id lobortis velit facilisis a.
Body Elements¶
Paragraphs¶
Paragraphs are simple blocks of text.
Warning
Paragraphs should be left-aligned
Blank lines separate paragraphs
Paragraphs syntax consists of plain text and Inline markup elements.
Code example
input: RST
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent cursus
tincidunt felis. *Suspendisse convallis semper faucibus*. In eleifend nisl
sit amet enim mollis, vitae eleifend orci euismod. Mauris vel nibh diam.
Quisque laoreet elit ac est fermentum auctor. Phasellus massa tortor,
interdum eu porta sed, malesuada sed erat. Morbi magna turpis, efficitur
a venenatis ac, consequat lobortis tortor. Maecenas iaculis est quis justo
facilisis, et elementum velit venenatis.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent cursus
tincidunt felis. Suspendisse convallis semper faucibus. In eleifend nisl
sit amet enim mollis, vitae eleifend orci euismod. Mauris vel nibh diam.
Quisque laoreet elit ac est fermentum auctor. Phasellus massa tortor,
interdum eu porta sed, malesuada sed erat. **Morbi magna** turpis, efficitur
a venenatis ac, consequat lobortis tortor. Maecenas iaculis est quis justo
facilisis, et elementum velit venenatis.
rendered: HTML
Sidebar¶
The sidebar is a floating element that allows you to place additional information parallel to the flow of your document.
Warning
Sidebars should not contain nested sidebars.
Sidebars can not be nested inside body elements.
Sidebar syntax follows the normal directive syntax. Remember that the directive argument is required for the sidebar.
Code example
input: RST
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent cursus
tincidunt felis. Suspendisse convallis semper faucibus.
.. sidebar:: Sidebar Title
:subtitle: Optional Sidebar Subtitle
Subsequent indented lines comprise
the body of the sidebar, and are
interpreted as body elements.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent cursus
tincidunt felis. Suspendisse convallis semper faucibus. In eleifend nisl
sit amet enim mollis, vitae eleifend orci euismod. Mauris vel nibh diam.
Quisque laoreet elit ac est fermentum auctor. Phasellus massa tortor,
interdum eu porta sed, malesuada sed erat. Morbi magna turpis, efficitur a
venenatis ac, consequat lobortis tortor. Maecenas iaculis est quis justo
facilisis, et elementum velit venenatis. Phasellus sit amet lobortis magna.
Cras fermentum nulla eros, id vestibulum felis feugiat ac. Mauris eget
libero ut ex mollis scelerisque sit amet vel lectus.
rendered: HTML
Sidebar Title
Optional Sidebar Subtitle
Subsequent indented lines comprise the body of the sidebar, and are interpreted as body elements.
Line blocks¶
Line blocks are helpful for writing content where having a particular text structure is needed. Line
blocks start with a non-indented vertical bar, |. Each of these vertical bars indicates a new
line of text. Each line beginning with the vertical bar takes into consideration whitespaces and tab
spaces.
Warning
A piece of text written in a new line might be considered the continuation of the previous line block.
Inline markup is supported.
Line block Syntax: consist of a vertical bar | prefix at the beginning of the text
line. If the text is a continuation of the previous line block, the text should begin with
whitespace instead of the vertical bar.
Code example
input: RST
| **NAME** top
|
| man - an interface to the
system reference manuals
|
| **SYNOPSIS** top
|
| man [man options] [[section] page ...] ...
| man -k [apropos options] regexp ...
| man -K [man options] [section] term ...
| man -f [whatis options] page ...
| man -l [man options] file ...
| man -w|-W [man options] page ...
rendered: HTML
Quotation¶
The RST markup language uses several syntaxes for writing quoted text. However, we will focus only
on two of them. The first quotation syntax is called block quotes, and the second quotation syntax
is called epigraph. The quotations are usually used to quote a piece of text or though that
someone else has write down or said. In order to indicate the author of the quote you must preceds the
author's name with double hyphens --.
Block quote¶
Block quotes are a relative indented text block, which is used to present quoted text.
Warning
A preceding text should exist because the block quote needs an anchor to evaluate whether or not it is a quoted text element. Otherwise, it might be considered a normal paragraph.
Block quote syntax consist of an indented text block (quoted text), and an attribution
(text preceded by doubled hyphens --).
Code example
input: RST
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent cursus tincidunt felis.
"It is my business to know things. That is my trade."
-- Sherlock Holmes
rendered: HTML
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent cursus tincidunt felis.
“It is my business to know things. That is my trade.”
—Sherlock Holmes
Epigraph¶
The epigraph works just as the block quote. However, the epigraph directive is independent of the text-flow, and therefore, there is no need for having an anchor text above the epigraph.
Warning
If you are quoting someone, remember to add the double hyphens
--at the end with the attribution
Epigraph syntax follows the normal directive syntax. This directive does not take any arguments, only content.
Code example
input: RST
.. epigraph::
No matter where you go, there you are.
-- Buckaroo Banzai
rendered: HTML
“ No matter where you go, there you are.”
—Buckaroo Banzai
Basic Lists¶
Lists are useful to present sequential information inside a document. In general, there are two types of lists, ordered and unordered. Nevertheless, there are also more specialised lists, such as the definition list. In this chapter we will cover these three types of lists.
Ordered lists¶
In RST ordered lists are often called enumerated lists. This list consists of several lines of text where each new line is preceded by a number that changes incrementally.
Warning
You must add a line break before the list.
Each item should be added in a new line.
Each element should start with the enumerated literal.
Nested list should be indented.
Enumerated lists syntax consist of an enumerated literal, followed by a dot, a whitespace and then the text that is considered the item in the list. Enumerated lists recognised several enumerated literals, as you can see in the table below.
Literal |
Semantic |
|---|---|
1., 2., 3. ... |
Arabic numerals |
#., #., #., ... |
auto incremental arabic numbers |
A., B., C., ... Z. |
uppercase alphabet characters |
a., b., c., ... z. |
lowercase alphabet characters |
I., II., III., ... |
uppercase roman numerals |
i., ii., iii., ... |
lowercase roman numerals |
Code example
input: RST
1. First Item
2. Second Item
A. First Item
B. Second Item
a. First Item
b. Second Item
rendered: HTML
- First Item
- Second Item
- First Item
- Second Item
- First Item
- Second Item
Unordered Lists¶
In RST, unordered lists are called bullet lists. This list consists of a sequence of elements with no enumeration whatsoever. Every item is preced by a bullet point.
Warning
You must add a line break before the list.
Each item should be added in a new line.
Each element should start with the bullet point literal.
Nested list should be indented.
Bullet lists syntax follow the same syntax as enumerated lists. However, the bullet
lists use different literals, among the bullet literal we can find the following ones: *, +,
-, • and ‣.
Code example
input: RST
* First Item
* Second Item
- First Item
- Second Item
rendered: HTML
- First Item
- Second Item
- First Item
- Second Item
Definition list¶
A definition list, is a special list that can be used to build a glossary or to describe program variables.
Warning
Blank lines are required before the first and after the last definition list item
You can use multiple classifiers. A classifier may be used to indicate the usage of the term (noun, verb, reserved word, etc.).
Definition lists syntax is relatively straightforward. Each definition list item contains a term, optional classifiers, and a definition. The term is just a one-line word. The optional classifier must come after the term. But between the term and the classifier there must be a whitespace, colon, and another whitespace. The definition is a block indented relatively to the term, and may contain multiple paragraphs and other body elements.
Code example
input: RST
term 1
Definition 1.
term 2
Definition 2, paragraph 1.
Definition 2, paragraph 2.
term 3 : classifier
Definition 3.
term 4 : classifier one : classifier two
Definition 4.
rendered: HTML
- term 1
- Definition 1.
- term 2
Definition 2, paragraph 1.
Definition 2, paragraph 2.
- term 3 : classifier
- Definition 3.
- term 4 : classifier one : classifier two
- Definition 4.
Tables¶
In RST, it is possible to create tables using a variety of directives and markup. In this guide,
we will present you with two types of tables. The first one is the so-called grid table, and the
second one is the simple table. Both tables are based on the table directive. The table
directive can be used to add an id, classes, and a label. The table directive also allows defining
the alignment, the width of the cells, and the width of the table itself.
Hint
Creating this type of tables can be cumbersome. Therefore, we suggest using some sort of table generator. We recommend using the following services:
Grid Table¶
Grid tables can be created using several visual elements. Symbols such as the pipe symbol |,
underscores _, hyphens -, equal sign = and the plus symbol + can be used to draw
your table. The example below shows better how the these symbols
are combined to create a grid table.
Warning
Blank lines are required before and after the grid table.
The left edges should be aligned with each other.
Grid table syntax is determined by the use of the ASCII characters. Once you have drawn your table, each individual cell is considered a miniature document.
Code example
input: RST
.. table:: Grid table example
:widths: auto
:name: grid-table-example
+----------+----------+----------+
| Header A | Header B | Header C |
+----------+----------+----------+
| Item 1a | Item 1b | None |
+----------+----------+----------+
| Item 1b | Item 2b | None |
| +---------+----------+
| | Item 2c | None |
+----------+----------+----------+
rendered: HTML
| Header A | Header B | Header C |
| Item 1a | Item 1b | None |
| Item 1b | Item 2b | None |
| Item 2c | None |
Simple Table¶
The simple table, as the name implies, has a simplistic way of drawing the table in your text editor. However, with this simpler approach comes some limitations in terms of cell layout. Simple tables can be used for simple data sets where a row contains a single data item.
Warning
Blank lines are required before and after the simple table.
Simple tables allow column spans, but not row spans.
Simple table syntax is determined by the use of the ASCII characters.
Code example
input: RST
.. table:: Simple table example
:class: table-striped table-bordered table-hover
:widths: auto
:name: simple-table-example
===== =====
A not A
===== =====
False True
True False
===== =====
rendered: HTML
| A | not A |
|---|---|
| False | True |
| True | False |
Code¶
Highlight directive¶
The most basic directive to add code snippets to your course content is the highlight directive.
This directive makes use of the built-in pygments library provided by Sphinx. As a result, the
snippets of code are rendered with a predefined code syntax higlighting.
Code highlighting can be enabled on a document-wide basis using the highlight directive.
Code highlighting can be also enabled on a project-wide basis using the highlight_language
configuration value inside
the conf.py file in your course.
Warning
When a highlight directive is encountered, it is used until the next highlight directive is encountered. If there is no highlight directive in the file, the global highlighting language is used.
Highlighting syntax consists of the directive name, the language identifier, and some
directive options. After the highlight directive has been configured, you can start adding code
snippets by adding double unindented colons ::. After the double colons you should add the
indented snippet of code.
Code example
input: RST
.. highlight:: rst
:linenothreshold: 1
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer ut tellus sapien. Morbi fermentum
in libero at porta. Curabitur sed accumsan dolor. Proin tortor turpis, dictum at libero quis,
pretium dapibus mi. Aliquam nec congue libero. Cras auctor ultrices ante, eget euismod velit
lobortis sit amet. Mauris facilisis odio ultrices, fringilla tellus ut, lacinia neque. Vestibulum ut
velit porta, viverra urna semper, blandit sem. In efficitur sodales eleifend. Donec ex est, fringilla
vitae mattis vel, aliquam ut tellus. Donec dapibus laoreet magna sed porta.
::
Title
=====
First snippet of code.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer ut tellus sapien. Morbi fermentum
in libero at porta. Curabitur sed accumsan dolor. Proin tortor turpis, dictum at libero quis,
pretium dapibus mi. Aliquam nec congue libero. Cras auctor ultrices ante, eget euismod velit
lobortis sit amet. Mauris facilisis odio ultrices, fringilla tellus ut, lacinia neque. Vestibulum ut
velit porta, viverra urna semper, blandit sem. In efficitur sodales eleifend. Donec ex est, fringilla
vitae mattis vel, aliquam ut tellus. Donec dapibus laoreet magna sed porta.
::
Title
=====
Second snippet of code.
rendered: HTML
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer ut tellus sapien. Morbi fermentum in libero at porta. Curabitur sed accumsan dolor. Proin tortor turpis, dictum at libero quis, pretium dapibus mi. Aliquam nec congue libero. Cras auctor ultrices ante, eget euismod velit lobortis sit amet. Mauris facilisis odio ultrices, fringilla tellus ut, lacinia neque. Vestibulum ut velit porta, viverra urna semper, blandit sem. In efficitur sodales eleifend. Donec ex est, fringilla vitae mattis vel, aliquam ut tellus. Donec dapibus laoreet magna sed porta.
1 2 3 4 | Title
=====
First snippet of code.
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer ut tellus sapien. Morbi fermentum in libero at porta. Curabitur sed accumsan dolor. Proin tortor turpis, dictum at libero quis, pretium dapibus mi. Aliquam nec congue libero. Cras auctor ultrices ante, eget euismod velit lobortis sit amet. Mauris facilisis odio ultrices, fringilla tellus ut, lacinia neque. Vestibulum ut velit porta, viverra urna semper, blandit sem. In efficitur sodales eleifend. Donec ex est, fringilla vitae mattis vel, aliquam ut tellus. Donec dapibus laoreet magna sed porta.
1 2 3 4 | Title
=====
Second snippet of code.
|
Admonition blocks¶
RST has an considerable list of admonitions blocks that are used to highlight pieces of information. However, on a more general level, the admonition blocks are divided into two types. The first type is known as the specific admonition. The second type is known as the generic admonition.
You can combine and use as many admonitions types as you wish. However, we strongly recommend to select only a few of them, and use them consistently throughout the course. As an example, you can see that in this course, we have only used the admonition type warning for common errors than can cause trouble while doing something, the admonition type note for adding information that might not fit the flow of the text, but is still relevant, and the admonition type hint for providing information that could help do things easier or faster. In addition to those specific admonitions, we use the generic admonition to define some terms that required an extended explanation. It may be also a good idea to explain to the students how you plan to use these admonition types throughout the course.
Specific¶
Specific admonitions are predefined admonition that might have a purpose within your document such as, add extra information, advise about some good practices, point out or alert about something.
Warning
The content of the admonition can be placed as a directive argument. However, that is considered a bad practice. It is better to place the content as directive content.
Specific admonition's syntax consists of the admonition type directive followed by the admonition content.
Code example
input: RST
.. warning::
This is a warning
.. note::
This is a note
.. hint::
This is a hint
rendered: HTML
Warning
This is a warning
Note
This is a note
Hint
This is a hint
Generic¶
Generic admonitions allow you to define the title and the content of the admonition. Similarly to the specific admonitions, the generic admonitions are rendered as an offset block in the document.
Generic admonition's syntax consists of the admonition type directive, a title and the admonition content.
Code example
input: RST
.. admonition:: reStructuredText
:class: meta
reStructuredText is plaintext that uses simple and intuitive constructs to indicate the
structure of a document. These constructs are equally easy to read in raw and processed
forms.
rendered: HTML
reStructuredText
reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document. These constructs are equally easy to read in raw and processed forms
Inline elements¶
Inline markup¶
It is always possible to add semantic meaning to your text, and inline markup allows you to do so. Inline markup applies to words or phrases within a text block.
Warning
The text within inline markup should not begin or end with whitespaces.
Inline markup cannot be nested.
Inline markup syntax consists of open and closed charactered with some text between
them. The characters that can be used to create inline semantic elements are: asterisk *,
double asterisk ** and backticks ``. The HTML representations of these inline elements are
the <strong>, <em> and <code> tags, respectively.
Code example
input: RST
*emphasis*
**strong emphasis**
``inline literals``
rendered: HTML
emphasis
strong emphasis
inline literals
Abbreviation¶
Abbreviation provides basic functionality for defining term on the fly. This RST role allows the end-user to hover over the specified term and see the metainformation related to that abbreviation in a tooltip.
Abbreviation syntax is represented with the :abrr: keyword. Within that backticks
that wrap the role content, you should place the abbreviation or term that you want to define, then
leave a whitespace, and then use parentheses to enclose the definition of the term.
Code example
input: RST
I can use abbreviations to define :abbr:`terms (This is a term definition)` on the fly.
rendered: HTML
I can use abbreviations to define terms on the fly
kbd roles¶
Kbd roles are used to specify a textual user input from a keyboard.
kbd syntax is represented with the :kbd: keyword. Within the backticks that wrap
the role content, you should place the keystroke you want to represent.
Code example
input: RST
Press the following keys in your keyboard. :kbd:`Ctrl` + :kbd:`s`
rendered: HTML
Press the following keys in your keyboard. Ctrl + s
Hyperlink¶
Hyperlinks can be used to link external websites or to link to different parts of the course content. In this section, we will cover hyperlinks that lead the users to external websites. For more information about internal links, you can see the Cross-reference section.
We have standalone links and embedded links with aliases. The standalone link's syntax
consists of a plain URI. The syntax of the embedded links with aliases consists of an opening
backtick, the alias text, whitespace, the less-than sign <, the URI, the greater-than
sign >, the closing backtick and finally an underscore.
Warning
The embedded links with aliases
No whitespace may be placed after the opening backtick.
No whitespace may be placed before the closing backtick.
Code example
input: RST
This is a standalone link https://docutils.sourceforge.io/docs/.
This is a link with an `alias <https://docutils.sourceforge.io/docs/>`_.
rendered: HTML
This is a standalone link https://docutils.sourceforge.io/docs/.
This is a link with an alias.