Techwriter at work blog.

Living and writing documentation at Documatt, small team of programmers that do write documentation too.

On this page

Sections – structuring document

Document structure is hierarchy of its sections. reStructuredText calls heading the section and takes different approach on section leveling than you probably expect. Section titles are decorated with the punctuation characters and importance (a section level) depends on its usage order in document.

Syntax

Section is text of title that is underlined, or both underlined and overlined, with same punctuation character. Decoration character is usually one (but not limited to [1] ) of the following:

= - ` : . ' " ~ ^ _ * + #

For example:

#####
Hello
#####

***********
How are you
***********

It's a beautiful day
====================

Even it's Monday
----------------

Section levels

Level is importance of section in the document. For example in HTML every section level has own element like <h1>, <h2> and so on. reStructuredText has different approach.

What level has sections in above example? Answer is in the order of decoration styles usage in the document. Example above uses four decoration styles (underlined, or both underlined and overlined) so you have four levels:

  • section with title “Hello” is underlined and overlined with # will become level 1 (top)

  • section with title “How are you” is underlined and overlined with * will become level 2

  • section with title “It’s beautiful day” is underlined with = will become level 3

  • section with title “Even it’s Monday” is underlined with - will become level 4

If above example each decoration style is used just once. First style will become level 1, second level 2 and so on.

If decoration style is used once again later, it’s still the same level. Have a look at more real-life example with repeated section levels:

#################
Planet Earth (L1)
#################

***********
Europe (L2)
***********

Great Britain (L3)
==================

Czech Republic (L3)
===================

******************
North America (L2)
******************

Canada (L3)
===========

United States (L3)
==================

Decoration style usage order to define section level has advantage you are not limited to e.g. six nesting levels as in HTML:

Section Title L1
================

Section Title L2
----------------

Section Title L3
````````````````

Section Title L4
''''''''''''''''

Section Title L5
................

Section Title L6
~~~~~~~~~~~~~~~~

Section Title L7
****************

Section Title L8
++++++++++++++++

Section Title L9
^^^^^^^^^^^^^^^^

Level convention

This flexibility is difficult at writing time to remember what style is what level. Therefore almost all reStructuredText tech-writers adhere the following prevalence convention (we used it in above examples too):

Section level

Decoration style

Suggested for

1

 
#######
Level 1
#######

Document titles

2

 
*******
Level 2
*******

Chapters

3

 
Level 3
=======

Sections

4

 
Level 4
-------

Subsections

5

 
Level 5
^^^^^^^

Subsubsections

6

 
Level 6
'''''''

Paragraphs

By this convention, first two the most important sections are both under- and overlined, the rest sections underlined only:

###############
This is section
###############

*************************************
The second the most important section
*************************************

Not so important section
========================

Rubrics

Sometimes is useful to use rubric, that is not really a section but looks like minor section similar for readers. Rubric is directive, not not technically a section, and don’t make up the table of content.

File devices
============

.. rubric:: Purpose

Blah blah blah

.. rubric:: The most useful file devices

Blah blah blah

Prefer sections instead rubrics

Often sections are preferred as more meaningful. Sections provide easy navigation because they make up table of contents.

For example instead

.. rubric:: Hidden files

Linux doesn't have hidden files. There is only convention that
files or folders that begin with dot are considered as hidden.
Therefore they are called dot-files.

you might use minor heading

Hidden files
^^^^^^^^^^^^

 Linux doesn't have hidden files. There is only convention that
 files or folders that begin with dot are considered as hidden.
 Therefore they are called dot-files.

Common issues

Same length decoration as title

reStructuredText is very strict about decoration character that must be exactly the same length as title, or longer (but it’s not too much aesthetic):

#########################
Correct length decoration
#########################

************************************************
Longer that title is okay too but ugly
************************************************

Shorted that title causes error
====================

Overline only is not allowed

Section title decorated only with overline is not allowed:

================
Will cause error

Under- and overline styles are different levels

Decoration style is couple of used character + underline or overline. The following decoration styles (and levels) are thus different:

################################
Level 1 is under- and over-lined
################################

********************************
Level 2 is under- and over-lined
********************************

Level 3 because it's only overlined
***********************************

Section must be on single line

Multiline section titles are actually recognized by reStructuredText as paragraph so no error or warning is thrown.

This is not multiline
section but paragraph
=====================

Footnotes

Comments

comments powered by Disqus