Home | History | Annotate | Download | only in doc
      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