Creating Manuals Using RST and Sphinx: Text Formatting

A close up of many old, random metal letters with copy space

ReStructuredText is one of the more persnickety documentation ‘languages’ out there. Blank lines and spaces can often be the difference between a lovely end document and absolute chaos. In this post, I’m going through the basic text formatting options that you’ll need to create a clear, readable document.

This article is part of a series documenting the process of creating manuals using reStructuredText and Sphinx. See the whole list of articles.

Heading text formatting

In reStructuredText, headings are designated by one or two lines of punctuation around the heading text, like this:

=================
This is a heading
=================

Or this:

This is also a heading
------------------------

Headings are a great example of RST’s persnicketiness. If you look closely enough at the examples above, you’ll note that they have some points in common. Firstly, they both have a line of punctuation under the text. That’s important. The punctuation marks above are optional; the punctuation marks below aren’t. Secondly, the line of punctuation marks are equal to or greater in length than the heading text. This is important; you’ll get errors appearing in your build logs if the number of characters in your punctuation line is less than the number of characters in your heading. I don’t know why this is. I’m sure there’s a reason for it.

Each heading can contain a different number of punctuation marks. For example, this is a perfectly acceptable RST document:

Writing RST
===========

Make sure that you remember to designate headings correctly. 

Heading levels in RST
==========================

Heading levels are designated by the **type** of punctuation used, not the number of punctuation marks. Both headings in this example will be interpreted as on the same level (eg. given <h1> tags in built HTML content).

Summary of heading rules

  • Must use one of these characters: ! ” # $ % & ‘ ( ) * + , – . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
  • Each line of punctuation must have as many or more characters than the heading text.
  • Must include a line of punctuation under the heading text.
  • A line of punctuation above the heading text may be included, but isn’t mandatory.

Heading levels

Sphinx will interpret the first heading style it encounters as a level 1 heading. The second heading style it encounters, it will interpret as a level 2 heading. And so on. It will expect heading styles to be in a logical order. For example, if it’s just encountered a level 1 heading, it will expect the next heading to be either level 1 or level 2. A level 3 or 4 heading will not be appreciated, and Sphinx will throw up a warning.

Consistency is very important. I recommend writing a quick style guide for your chosen heading designations, because a) there’s a chance you’ll forget which punctuation goes with which heading style, and b) other people might need to work on your documentation.

Spacing

You might have noticed that I always leave a blank line between a heading and the following paragraph text. This is not a stylistic choice. Blank lines are very important to Sphinx – they designate style or block changes. So this is incorrect usage:

Heading text
============
This paragraph text won't be interpreted correctly.

But this is correct:

Heading text
============

This text will be interpreted as its own paragraph.

In some situations, a new line without a blank line is interpreted as a line break (<br />).

Character text formatting

You have all the basic character text formatting options: bold, italic, monospaced. These are used within paragraphs, to specify formatting for a character, word, or phrase. Generally, you shouldn’t be using these formatting options for an entire paragraph.

Bold

Designate bold text with **. If you build to HTML, this will be interpreted with <strong> tags. If you build to LaTeX, this will be interpreted with \textbf (bold) tags.

The difference between strong and bold tags can be important, especially around accessibility. See this article for more information: Accessibility: Bold vs. Strong and Italic vs. Emphasis.

For example:

It's very important to understand text formatting. To designate **bold text**, use two asterisks before and after the text to be bolded.

The RST will be interpreted to look something like this:

It’s very important to understand text formatting. To designate bold text, use two asterisks before and after the text to be bolded.

Italics

Designate italic text with *. If you build to HTML, this will be interpreted with <em> tags. If you build to LaTeX, this will be interpreted with \emph tags.

As with bold/strong tags, the difference between italic and emphasis tags can be important to people using accessibility aids. The same article mentioned above also contains information on using italic and emphasis: Accessibility: Bold vs. Strong and Italic vs. Emphasis.

For example:

It's easy to create *italic text*. Just use one asterisk before and after the text to be italicised.

The RST will be interpreted to look something like this:

It’s easy to create italic text. Just use one asterisk before and after the text to be italicised.

Code

Designate monospaced text with ``. If you build to HTML, this will be interpreted with <code> tags. If you build to LaTeX, it will be interpreted with \\texttt tags.

For example:

It's easy to create ``monospaced text`` within a paragraph. Just use two back-tick (also known as back-quote or accent grave) characters before and after the text you want to appear in a monospace font.

The RST will be interpreted to look something like this:

It’s easy to create monospaced text within a paragraph. Just use two back-tick (also known as back-quote or accent grave) characters before and after the text you want to appear in a monospace font.

Using formatting characters as text

Using punctuation marks as text formatting codes causes an issue: what if you want to use them as straight punctuation marks instead? This is where ‘escaping‘ comes in.

If you’re not from a programming background: escaping tells a code interpreter (in this case, Sphinx) that the following character should be treated as plain text and not part of the code.

The backslash is RST’s escape character. Add it before a character that’s used to code text formatting and the like.

For example: I want my sentence to display an asterisk, but I know that Sphinx will interpret an asterisk as the start of italic text. This is how I put the sentence together in RST:

The asterisk (\*) is a very useful little character. It can stand in for missing letters (G\*d) or highlight an important word or phrase (this is the \*best\* idea ever!) when text formatting is not available.

The RST will be interpreted to look something like this:

The asterisk (*) is a very useful little character. It can stand in for missing letters (G*d) or highlight an important word or phrase (this is the *best* idea ever!) when text formatting is not available.

Block formatting

Block formatting applies text and paragraph formatting to an entire block (multiple lines or paragraphs) of text.

List

There are two types of list available: bulleted and numbered.

Bulleted list

Use an asterisk (*) to designate bulleted list items.

For example:

* Sphinx will turn this into a bulleted list item.
* Sphinx will make this the second item in the bulleted list.

Sphinx will interpret the above to look something like this:

  • Sphinx will turn this into a bulleted list item.
  • Sphinx will make this the second item in the bulleted list.

Numbered list

Use numbers or (my preference) hashes (#) to designate numbered list items. Using hashes allows Sphinx to auto-number the list.

For example:

# Sphinx will interpret this as a numbered list item.
# Sphinx will interpret this as the second item in the numbered list.

Sphinx will interpret it to look like:

  1. Sphinx will interpret this as a numbered list item.
  2. Sphinx will interpret this as the second item in the numbered list.

Code block

There are two ways to create a block of code:

  • Use a literal block.
  • Use a code-block directive.

I prefer using the code-block directive. It’s more specific, and you can add some neat formatting that isn’t available with the other format.

Literal block

Create a literal block by adding two colons (::) to the end of a line and indenting all lines that you want in the literal block.

For example: I want to show some html code in a literal block. I use the following RST code:

Use this CSS to create a flexbox on your HTML page::

   .flexible {
      display: flex;
      flex-flow: row wrap; 
      height: 300px;
      align-items: center; 
   } 

The RST will be interpreted to look something like this:

Use this CSS to create a flexbox on your HTML page:

.flexible {
   display: flex;
   flex-flow: row wrap; 
   height: 300px;
   align-items: center; 
} 

Note that Sphinx does two things with the double colon in this example:

  • Recognised the following indented text as a code block.
  • Replaced it with a colon character in the resulting text.

code-block directive

You can also use a directive to indicate a block of code. I like this option because it’s more customisable, and there are some cool features.

The basic code-block directive looks like this:

.. code-block:: <language>

For example:

.. code-block:: html

However, there are also parameters that you can include:

  • :linenos: – add a line number to each line of code.
  • :lineno-start: – start numbering lines of code at a specified number.
  • :emphasize-lines: – bold certain lines of code. Separate line numbers with commas; include multiple lines using a hyphen.
  • :caption: – adds a caption below the code block.
  • :name: – a unique identifier for the code block. You can then link to the code block using the :ref: command.

For example:

.. code-block:: ruby
   :linenos:
   :line-no-start: 30
   :emphasize-lines: 32-34

   print "Writing a code block in RST.\n" 
   print "We've set up line numbers.\n"
   print "Now you can see which are emphasised.\n"
   print "Do this when you want to draw the reader's attention\n"
   print "to specific lines in a function.\n"
   print "It's a useful tool."   

Sphinx will interpret the above to look something like this:

 30   print "Writing a code block in RST.\n" 
 31   print "We've set up line numbers.\n"
 32   print "Now you can see which are emphasised.\n"
 33   print "Do this when you want to draw the reader's attention\n"
 34   print "to specific lines in a function.\n"
 35   print "It's a useful tool."  

Blockquote

To create a blockquote paragraph, indent the text.

For example:

Here's a blockquote:

   This is the blockquote.
   It's pretty simple.
   It will continue until you stop indenting the text.

Sphinx will interpret the above to look something like this:

Here’s a blockquote:

This is the blockquote.

It’s pretty simple.

It will continue until you stop indenting the text.

Other text formatting options

There are more options than I’ve covered, but the ones above will cover you in most circumstances. I’ll put together an advanced formatting post later.

 

Leave a Reply

Your email address will not be published. Required fields are marked *