1 .. _getting_started: 2 3 :orphan: 4 5 #################################################### 6 Examples of ReST markup for devsite (Document title) 7 #################################################### 8 9 This is an auto-generated table of contents for this document. ``:local:`` and 10 ``:backlinks: none`` are required to make the devsite look consistent; 11 ``:depth:`` level can be controlled. 12 13 .. contents:: 14 :local: 15 :backlinks: none 16 :depth: 2 17 18 Document structure 19 ================== 20 21 A document starts with a Sphinx target which serves as the document name 22 throughout the tree. It can serve as a link target in other documents that want 23 to link to this one (see the Links section below). 24 25 It follows with the document title (which doesn't get generated to the HTML body 26 in production mode, but is picked up by the devsite from ``<head><title>``. 27 28 Basic markup 29 ============ 30 31 In general, follow the rules from http://sphinx-doc.org/rest.html 32 33 Some **bold text** and *italic text* and ``fixed-font text``. Non marked-up text 34 can follow these immediately by using a backslash: **pexe**\s. 35 36 For pleasant collaborative editing, please use the accepted coding guidelines: 37 wrap at 80 columns, no tabs, etc. 38 39 Quotes (``<blockquote>``) are created by indenting the paragraph: 40 41 Most good programmers do programming not because they expect to get paid or 42 get adulation by the public, but because it is fun to program. 43 -- Linus Torvalds 44 45 Here's an en-dash -- and an m-dash --- too. 46 47 Unicode samples 48 --------------- 49 50 Copyright sign |copy|, and uacute |Uacute|. 51 52 .. |copy| unicode:: 0xA9 .. copyright 53 .. |Uacute| unicode:: U+000DA 54 55 56 Images 57 ====== 58 59 Please use absolute paths (starting with ``/``) for images: 60 61 .. image:: /images/NaclBlock.png 62 63 Links 64 ===== 65 66 To other documents within the tree 67 ---------------------------------- 68 69 Internal links to other documents are created :doc:`like this <overview>`. The 70 document name within the angle brackets is relative to the root dir of the 71 devsite doc tree and does not have an extension. 72 73 Here's a link to a document in a subdirectory: :doc:`the tutorial 74 <devguide/tutorial/tutorial-part1>`. And a link to a subdirectory index page 75 :doc:`devguide index <devguide/index>`. 76 77 To sections inside documents 78 ---------------------------- 79 80 To internal locations within documents, labels are used. For example, this link 81 goes to the label explicitly placed in this document - 82 :ref:`link_for_section_heading`. This works across documents as well. Label 83 names must be unique in the tree, and can refer to anything (like images). 84 85 It's also possible to give such cross-references custom names: :ref:`Same 86 Section Heading<link_for_section_heading>`. 87 88 To external locations 89 --------------------- 90 91 Plain links can be placed like this: http://google.com and also `like this 92 <http://google.com>`_. 93 94 Definition lists 95 ================ 96 97 Can be used to define a group of related terms. Internal formatting is supported 98 within the definition. No special formatting needs to be done for the definition 99 name/title - it's handled by the devsite. 100 101 Apple 102 The apple is the pomaceous fruit of the apple tree, species Malus domestica in 103 the rose family (**Rosaceae**). 104 Fig 105 The common fig (**Ficus carica**) is a species of flowering plant in the genus 106 Ficus, from the family Moraceae, known as the common fig (or just the fig), 107 anjeer (Iran, Pakistan), and dumur (Bengali). 108 Pear 109 The pear is any of several tree and shrub species of genus Pyrus, in the 110 family Rosaceae. 111 112 Notes and Admonitions 113 ===================== 114 115 The devsite supports special "notes" that are indented and have a background 116 color. We'll generate them with the ``Note`` directive, providing the class 117 explicitly. The class is one of ``note``, ``caution``, ``warning``, 118 ``special``. 119 120 .. Note:: 121 :class: note 122 123 This is a note. 124 125 Foo bar. 126 127 Also: 128 129 .. Note:: 130 :class: caution 131 132 Caution -- you have been warned. 133 134 Source code 135 =========== 136 137 Here's source code that will be pretty-printed on the devsite. Outside 138 production mode, it's just a plain ``<pre>`` that presents pre-formatted code 139 without coloring: 140 141 .. naclcode:: 142 143 #include <iostream> 144 145 int main() { 146 char c = 'x'; 147 std::cout << "Hello world\n"; 148 return 0; 149 } 150 151 For some code (like shell samples), we want to disable pretty-printing: 152 153 .. naclcode:: 154 :prettyprint: 0 155 156 $ ls | wc 157 $ echo "hello world" 158 159 By default ``:prettyprint:`` is ``1``. 160 161 For short inline code, use fixed-formatting like ``int x = 2;``. Note that this 162 won't get syntax-highlighted and may be line-wrapped, so keep it very short. 163 164 .. _link_for_section_heading: 165 166 Section heading 167 =============== 168 169 Here's a demonstration of heading nesting levels. This is a top-level section in 170 the document. The document title is the first header and it's delimited by hash 171 signes (``#``) from above and below. 172 173 Subsection heading 174 ------------------ 175 176 Subsection. 177 178 Sub-subsection heading 179 ^^^^^^^^^^^^^^^^^^^^^^ 180 181 That's pretty deep... 182 183 Sub-sub-subsection heading 184 """""""""""""""""""""""""" 185 186 It's probably not the best idea to go this far (renders to ``<h5>``). 187 188 Expandable sections 189 =================== 190 191 The devsite can render expandable sections when a special ``class`` is applied. 192 This can be achieved by specifying the ``rst-class`` immediately before a 193 section (or any other element), as follows: 194 195 .. rst-class:: expandable 196 197 Expandable Section 198 ------------------ 199 200 Look, ma! I'm expandable! 201 202 Lists 203 ===== 204 205 Auto-numbered ordered lists: 206 207 #. One 208 #. Two 209 #. Three 210 211 Manually numbered ordered lists: 212 213 1. One 214 2. Two 215 3. Three 216 217 Unordered (bullet) lists: 218 219 * One 220 * Two 221 * Three 222 223 Lists can be nested and mixed too: 224 225 * Toplevel 226 227 1. One 228 2. Two 229 230 * Back to top level 231 232 Tables 233 ====== 234 235 The full scoop on tables is http://sphinx-doc.org/rest.html#tables and the 236 Docutils pages linked from it. 237 238 "Simple tables" require less markup but are limited: 239 240 ===== ===== ======= 241 A B A and B 242 ===== ===== ======= 243 False False False 244 True False False 245 False True False 246 True True True 247 ===== ===== ======= 248 249 "Grid tables" are versatile but require more markup: 250 251 +------------------------+------------+----------+----------+ 252 | Header row, column 1 | Header 2 | Header 3 | Header 4 | 253 | (header rows optional) | | | | 254 +========================+============+==========+==========+ 255 | body row 1, column 1 | column 2 | column 3 | column 4 | 256 +------------------------+------------+----------+----------+ 257 | body row 2 | ... | ... | | 258 +------------------------+------------+----------+----------+ 259 260
