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 2section with title “It’s beautiful day” is underlined with
=
will become level 3section 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