1A ReStructuredText Primer 2========================= 3 4:Author: Richard Jones 5:Version: $Revision: 5801 $ 6:Copyright: This document has been placed in the public domain. 7 8.. contents:: 9 10 11The text below contains links that look like "(quickref__)". These 12are relative links that point to the `Quick reStructuredText`_ user 13reference. If these links don't work, please refer to the `master 14quick reference`_ document. 15 16__ 17.. _Quick reStructuredText: quickref.html 18.. _master quick reference: 19 http://docutils.sourceforge.net/docs/user/rst/quickref.html 20 21.. Note:: This document is an informal introduction to 22 reStructuredText. The `What Next?`_ section below has links to 23 further resources, including a formal reference. 24 25 26Structure 27--------- 28 29From the outset, let me say that "Structured Text" is probably a bit 30of a misnomer. It's more like "Relaxed Text" that uses certain 31consistent patterns. These patterns are interpreted by a HTML 32converter to produce "Very Structured Text" that can be used by a web 33browser. 34 35The most basic pattern recognised is a **paragraph** (quickref__). 36That's a chunk of text that is separated by blank lines (one is 37enough). Paragraphs must have the same indentation -- that is, line 38up at their left edge. Paragraphs that start indented will result in 39indented quote paragraphs. For example:: 40 41 This is a paragraph. It's quite 42 short. 43 44 This paragraph will result in an indented block of 45 text, typically used for quoting other text. 46 47 This is another one. 48 49Results in: 50 51 This is a paragraph. It's quite 52 short. 53 54 This paragraph will result in an indented block of 55 text, typically used for quoting other text. 56 57 This is another one. 58 59__ quickref.html#paragraphs 60 61 62Text styles 63----------- 64 65(quickref__) 66 67__ quickref.html#inline-markup 68 69Inside paragraphs and other bodies of text, you may additionally mark 70text for *italics* with "``*italics*``" or **bold** with 71"``**bold**``". This is called "inline markup". 72 73If you want something to appear as a fixed-space literal, use 74"````double back-quotes````". Note that no further fiddling is done 75inside the double back-quotes -- so asterisks "``*``" etc. are left 76alone. 77 78If you find that you want to use one of the "special" characters in 79text, it will generally be OK -- reStructuredText is pretty smart. 80For example, this lone asterisk * is handled just fine, as is the 81asterisk in this equation: 5*6=30. If you actually 82want text \*surrounded by asterisks* to **not** be italicised, then 83you need to indicate that the asterisk is not special. You do this by 84placing a backslash just before it, like so "``\*``" (quickref__), or 85by enclosing it in double back-quotes (inline literals), like this:: 86 87 ``*`` 88 89__ quickref.html#escaping 90 91.. Tip:: Think of inline markup as a form of (parentheses) and use it 92 the same way: immediately before and after the text being marked 93 up. Inline markup by itself (surrounded by whitespace) or in the 94 middle of a word won't be recognized. See the `markup spec`__ for 95 full details. 96 97__ ../../ref/rst/restructuredtext.html#inline-markup 98 99 100Lists 101----- 102 103Lists of items come in three main flavours: **enumerated**, 104**bulleted** and **definitions**. In all list cases, you may have as 105many paragraphs, sublists, etc. as you want, as long as the left-hand 106side of the paragraph or whatever aligns with the first line of text 107in the list item. 108 109Lists must always start a new paragraph -- that is, they must appear 110after a blank line. 111 112**enumerated** lists (numbers, letters or roman numerals; quickref__) 113 __ quickref.html#enumerated-lists 114 115 Start a line off with a number or letter followed by a period ".", 116 right bracket ")" or surrounded by brackets "( )" -- whatever you're 117 comfortable with. All of the following forms are recognised:: 118 119 1. numbers 120 121 A. upper-case letters 122 and it goes over many lines 123 124 with two paragraphs and all! 125 126 a. lower-case letters 127 128 3. with a sub-list starting at a different number 129 4. make sure the numbers are in the correct sequence though! 130 131 I. upper-case roman numerals 132 133 i. lower-case roman numerals 134 135 (1) numbers again 136 137 1) and again 138 139 Results in (note: the different enumerated list styles are not 140 always supported by every web browser, so you may not get the full 141 effect here): 142 143 1. numbers 144 145 A. upper-case letters 146 and it goes over many lines 147 148 with two paragraphs and all! 149 150 a. lower-case letters 151 152 3. with a sub-list starting at a different number 153 4. make sure the numbers are in the correct sequence though! 154 155 I. upper-case roman numerals 156 157 i. lower-case roman numerals 158 159 (1) numbers again 160 161 1) and again 162 163**bulleted** lists (quickref__) 164 __ quickref.html#bullet-lists 165 166 Just like enumerated lists, start the line off with a bullet point 167 character - either "-", "+" or "*":: 168 169 * a bullet point using "*" 170 171 - a sub-list using "-" 172 173 + yet another sub-list 174 175 - another item 176 177 Results in: 178 179 * a bullet point using "*" 180 181 - a sub-list using "-" 182 183 + yet another sub-list 184 185 - another item 186 187**definition** lists (quickref__) 188 __ quickref.html#definition-lists 189 190 Unlike the other two, the definition lists consist of a term, and 191 the definition of that term. The format of a definition list is:: 192 193 what 194 Definition lists associate a term with a definition. 195 196 *how* 197 The term is a one-line phrase, and the definition is one or more 198 paragraphs or body elements, indented relative to the term. 199 Blank lines are not allowed between term and definition. 200 201 Results in: 202 203 what 204 Definition lists associate a term with a definition. 205 206 *how* 207 The term is a one-line phrase, and the definition is one or more 208 paragraphs or body elements, indented relative to the term. 209 Blank lines are not allowed between term and definition. 210 211 212Preformatting (code samples) 213---------------------------- 214(quickref__) 215 216__ quickref.html#literal-blocks 217 218To just include a chunk of preformatted, never-to-be-fiddled-with 219text, finish the prior paragraph with "``::``". The preformatted 220block is finished when the text falls back to the same indentation 221level as a paragraph prior to the preformatted block. For example:: 222 223 An example:: 224 225 Whitespace, newlines, blank lines, and all kinds of markup 226 (like *this* or \this) is preserved by literal blocks. 227 Lookie here, I've dropped an indentation level 228 (but not far enough) 229 230 no more example 231 232Results in: 233 234 An example:: 235 236 Whitespace, newlines, blank lines, and all kinds of markup 237 (like *this* or \this) is preserved by literal blocks. 238 Lookie here, I've dropped an indentation level 239 (but not far enough) 240 241 no more example 242 243Note that if a paragraph consists only of "``::``", then it's removed 244from the output:: 245 246 :: 247 248 This is preformatted text, and the 249 last "::" paragraph is removed 250 251Results in: 252 253:: 254 255 This is preformatted text, and the 256 last "::" paragraph is removed 257 258 259Sections 260-------- 261 262(quickref__) 263 264__ quickref.html#section-structure 265 266To break longer text up into sections, you use **section headers**. 267These are a single line of text (one or more words) with adornment: an 268underline alone, or an underline and an overline together, in dashes 269"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the 270non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you 271feel comfortable with. An underline-only adornment is distinct from 272an overline-and-underline adornment using the same character. The 273underline/overline must be at least as long as the title text. Be 274consistent, since all sections marked with the same adornment style 275are deemed to be at the same level:: 276 277 Chapter 1 Title 278 =============== 279 280 Section 1.1 Title 281 ----------------- 282 283 Subsection 1.1.1 Title 284 ~~~~~~~~~~~~~~~~~~~~~~ 285 286 Section 1.2 Title 287 ----------------- 288 289 Chapter 2 Title 290 =============== 291 292This results in the following structure, illustrated by simplified 293pseudo-XML:: 294 295 <section> 296 <title> 297 Chapter 1 Title 298 <section> 299 <title> 300 Section 1.1 Title 301 <section> 302 <title> 303 Subsection 1.1.1 Title 304 <section> 305 <title> 306 Section 1.2 Title 307 <section> 308 <title> 309 Chapter 2 Title 310 311(Pseudo-XML uses indentation for nesting and has no end-tags. It's 312not possible to show actual processed output, as in the other 313examples, because sections cannot exist inside block quotes. For a 314concrete example, compare the section structure of this document's 315source text and processed output.) 316 317Note that section headers are available as link targets, just using 318their name. To link to the Lists_ heading, I write "``Lists_``". If 319the heading has a space in it like `text styles`_, we need to quote 320the heading "```text styles`_``". 321 322 323Document Title / Subtitle 324````````````````````````` 325 326The title of the whole document is distinct from section titles and 327may be formatted somewhat differently (e.g. the HTML writer by default 328shows it as a centered heading). 329 330To indicate the document title in reStructuredText, use a unique adornment 331style at the beginning of the document. To indicate the document subtitle, 332use another unique adornment style immediately after the document title. For 333example:: 334 335 ================ 336 Document Title 337 ================ 338 ---------- 339 Subtitle 340 ---------- 341 342 Section Title 343 ============= 344 345 ... 346 347Note that "Document Title" and "Section Title" above both use equals 348signs, but are distict and unrelated styles. The text of 349overline-and-underlined titles (but not underlined-only) may be inset 350for aesthetics. 351 352 353Images 354------ 355 356(quickref__) 357 358__ quickref.html#directives 359 360To include an image in your document, you use the the ``image`` directive__. 361For example:: 362 363 .. image:: images/biohazard.png 364 365results in: 366 367.. image:: images/biohazard.png 368 369The ``images/biohazard.png`` part indicates the filename of the image 370you wish to appear in the document. There's no restriction placed on 371the image (format, size etc). If the image is to appear in HTML and 372you wish to supply additional information, you may:: 373 374 .. image:: images/biohazard.png 375 :height: 100 376 :width: 200 377 :scale: 50 378 :alt: alternate text 379 380See the full `image directive documentation`__ for more info. 381 382__ ../../ref/rst/directives.html 383__ ../../ref/rst/directives.html#images 384 385 386What Next? 387---------- 388 389This primer introduces the most common features of reStructuredText, 390but there are a lot more to explore. The `Quick reStructuredText`_ 391user reference is a good place to go next. For complete details, the 392`reStructuredText Markup Specification`_ is the place to go [#]_. 393 394Users who have questions or need assistance with Docutils or 395reStructuredText should post a message to the Docutils-users_ mailing 396list. 397 398.. [#] If that relative link doesn't work, try the master document: 399 http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. 400 401.. _reStructuredText Markup Specification: 402 ../../ref/rst/restructuredtext.html 403.. _Docutils-users: ../mailing-lists.html#docutils-users 404.. _Docutils project web site: http://docutils.sourceforge.net/ 405
