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