native_client_sdk/src/doc/rest-devsite-examples.rst

   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