TESTING AREA for teachers - real service at plus.tuni.fi

This course has already ended.

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:
  1. You only need basic computing and programming skills, prior knowledge about markup languages might be beneficial.
  2. A basic environment set-up, as detailed in Module 2.
  3. 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.

  1. RST is sensitive to indentation.
  2. RST requires blank lines between paragraphs and between directives.
  3. RST directives and roles are case-insensitive.
Read more about RST syntax

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
= (equal sign) Title of the chapter. You should have just one Title per chapter.
- (hyphen) Subtitle
. (dot) Subsubtitle
' (apostrophe) 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.

Read more about titles

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.

Read more about transitions.

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

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.

Read more about paragraphs

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

Fragment of the Linux man documentation
| **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

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 …

Read more about line blocks

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

Read more about blocks quotes

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

Read more about epigraphs

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

  1. First Item
  2. Second Item

  1. First Item
  2. Second Item
  1. First Item
  2. Second Item

Read more about enumerated lists

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

Read more about bullet lists

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.

Read more about definition lists

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

Grid table example
Header A Header B Header C
Item 1a Item 1b None
Item 1b Item 2b None
Item 2c None

Read more about grid tables

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

Simple table example
A not A
False True
True False

Read more about simple tables

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.

Read more about the highlight directive

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

Read more about specific admonitions

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

Read more about generic admonitions

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

Read more about inline markup.

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

Read more about abbreviations.

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

Read more about kbd.

Posting submission...