Contents

• A ReStructuredText Primer
  • Structure
  • Text styles
  • Lists
  • Preformatting (code samples)
  • Sections
    • Document Title / Subtitle
  • Images
  • What Next?

注解

This document is an informal introduction toreStructuredText. TheWhat Next? section below has links tofurther resources, including a formal reference.

5.1. Structure¶

From the outset, let me say that “Structured Text” is probably a bitof a misnomer. It’s more like “Relaxed Text” that uses certainconsistent patterns. These patterns are interpreted by a HTMLconverter to produce “Very Structured Text” that can be used by a webbrowser.

The most basic pattern recognised is aparagraph (quickref).That’s a chunk of text that is separated by blank lines (one isenough). Paragraphs must have the same indentation – that is, lineup at their left edge. Paragraphs that start indented will result inindented quote paragraphs. For example:

This is a paragraph.  It's quiteshort.   This paragraph will result in an indented block of   text, typically used for quoting other text.This is another one.

Results in:

This is a paragraph. It’s quiteshort.

This paragraph will result in an indented block oftext, typically used for quoting other text.

This is another one.

5.2. Text styles¶

(quickref)

Inside paragraphs and other bodies of text, you may additionally marktext foritalics with “*italics*” orbold with“**bold**”. This is called “inline markup”.

If you want something to appear as a fixed-space literal, use“``doubleback-quotes``”. Note that no further fiddling is doneinside the double back-quotes – so asterisks “*” etc. are leftalone.

If you find that you want to use one of the “special” characters intext, it will generally be OK – reStructuredText is pretty smart.For example, this lone asterisk * is handled just fine, as is theasterisk in this equation: 5*6=30. If you actuallywant text *surrounded by asterisks* tonot be italicised, thenyou need to indicate that the asterisk is not special. You do this byplacing a backslash just before it, like so “\*” (quickref), orby enclosing it in double back-quotes (inline literals), like this:

``*``

5.3. Lists¶

Lists of items come in three main flavours:enumerated,bulleted anddefinitions. In all list cases, you may have asmany paragraphs, sublists, etc. as you want, as long as the left-handside of the paragraph or whatever aligns with the first line of textin the list item.

Lists must always start a new paragraph – that is, they must appearafter a blank line.

enumerated lists (numbers, letters or roman numerals;quickref)

Start a line off with a number or letter followed by a period ”.”,right bracket ”)” or surrounded by brackets “( )” – whatever you’recomfortable with. All of the following forms are recognised:

1. numbersA. upper-case letters   and it goes over many lines   with two paragraphs and all!a. lower-case letters   3. with a sub-list starting at a different number   4. make sure the numbers are in the correct sequence though!I. upper-case roman numeralsi. lower-case roman numerals(1) numbers again1) and again

Results in (note: the different enumerated list styles are notalways supported by every web browser, so you may not get the fulleffect here):

1. numbers

1. upper-case lettersand it goes over many lines

   with two paragraphs and all!

1. lower-case letters
   3. with a sub-list starting at a different number
   4. make sure the numbers are in the correct sequence though!

1. upper-case roman numerals

1. lower-case roman numerals

1. numbers again

1. and again

bulleted lists (quickref)

Just like enumerated lists, start the line off with a bullet pointcharacter - either “-”, “+” or “*”:

* a bullet point using "*"  - a sub-list using "-"    + yet another sub-list  - another item

Results in:

• a bullet point using “*”
  • a sub-list using “-“
    • yet another sub-list
  • another item

definition lists (quickref)

Unlike the other two, the definition lists consist of a term, andthe definition of that term. The format of a definition list is:

what  Definition lists associate a term with a definition.*how*  The term is a one-line phrase, and the definition is one or more  paragraphs or body elements, indented relative to the term.  Blank lines are not allowed between term and definition.

Results in:

what

Definition lists associate a term with a definition.

how

The term is a one-line phrase, and the definition is one or moreparagraphs or body elements, indented relative to the term.Blank lines are not allowed between term and definition.

5.4. Preformatting (code samples)¶

(quickref)

To just include a chunk of preformatted, never-to-be-fiddled-withtext, finish the prior paragraph with “::”. The preformattedblock is finished when the text falls back to the same indentationlevel as a paragraph prior to the preformatted block. For example:

An example::    Whitespace, newlines, blank lines, and all kinds of markup      (like *this* or \this) is preserved by literal blocks.  Lookie here, I've dropped an indentation level  (but not far enough)no more example

Results in:

An example:

  Whitespace, newlines, blank lines, and all kinds of markup    (like *this* or \this) is preserved by literal blocks.Lookie here, I've dropped an indentation level(but not far enough)

no more example

Note that if a paragraph consists only of “::”, then it’s removedfrom the output:

::    This is preformatted text, and the    last "::" paragraph is removed

Results in:

This is preformatted text, and thelast "::" paragraph is removed

5.5. Sections¶

(quickref)

To break longer text up into sections, you usesection headers.These are a single line of text (one or more words) with adornment: anunderline alone, or an underline and an overline together, in dashes“-----”, equals “======”, tildes “~~~~~~” or any of thenon-alphanumeric characters=-`:'"~^_*+#<> that youfeel comfortable with. An underline-only adornment is distinct froman overline-and-underline adornment using the same character. Theunderline/overline must be at least as long as the title text. Beconsistent, since all sections marked with the same adornment styleare deemed to be at the same level:

Chapter 1 Title===============Section 1.1 Title-----------------Subsection 1.1.1 Title~~~~~~~~~~~~~~~~~~~~~~Section 1.2 Title-----------------Chapter 2 Title===============

This results in the following structure, illustrated by simplifiedpseudo-XML:

<section>    <title>        Chapter 1 Title    <section>        <title>            Section 1.1 Title        <section>            <title>                Subsection 1.1.1 Title    <section>        <title>            Section 1.2 Title<section>    <title>        Chapter 2 Title

(Pseudo-XML uses indentation for nesting and has no end-tags. It’snot possible to show actual processed output, as in the otherexamples, because sections cannot exist inside block quotes. For aconcrete example, compare the section structure of this document’ssource text and processed output.)

Note that section headers are available as link targets, just usingtheir name. To link to theLists heading, I write “Lists_”. Ifthe heading has a space in it liketext styles, we need to quotethe heading “`textstyles`_”.

================ Document Title================---------- Subtitle----------Section Title=============...

5.6. Images¶

(quickref)

To include an image in your document, you use the theimagedirective.For example:

.. image:: images/biohazard.png

results in:

Theimages/biohazard.png part indicates the filename of the imageyou wish to appear in the document. There’s no restriction placed onthe image (format, size etc). If the image is to appear in HTML andyou wish to supply additional information, you may:

.. image:: images/biohazard.png   :height: 100   :width: 200   :scale: 50   :alt: alternate text

See the fullimage directive documentation for more info.

5.7. What Next?¶

This primer introduces the most common features of reStructuredText,but there are a lot more to explore. TheQuick reStructuredTextuser reference is a good place to go next. For complete details, thereStructuredText Markup Specification is the place to go[1].

Users who have questions or need assistance with Docutils orreStructuredText should post a message to theDocutils-users mailinglist.