1 ====

     2 Book

     3 ====

     4 

     5 ----

     6 Part

     7 ----

     8 

     9 Chapter

    10 =======

    11 

    12 .. _Level1AnchorForLaterReference:

    13 

    14 Level 1 section

    15 ---------------

    16 

    17 Level 2 section

    18 ~~~~~~~~~~~~~~~

    19 

    20 Level 3 section

    21 ```````````````

    22 

    23 

    24 

    25 *CubicWeb*

    26 

    27 

    28 inline directives:

    29   :file:`directory/file`

    30   :envvar:`AN_ENV_VARIABLE`

    31   :command:`command --option arguments`

    32 

    33   :ref:, :mod:

    34 

    35 

    36 .. sourcecode:: python

    37 

    38    class SomePythonCode:

    39      ...

    40 

    41 .. XXX a comment, wont be rendered

    42 

    43 

    44 a [foot note]_

    45 

    46 .. [foot note] the foot note content

    47 

    48 

    49 Boxes

    50 =====

    51 

    52 - warning box: 

    53     .. warning::

    54 

    55        Warning content

    56 - note box:

    57     .. note::

    58 

    59        Note content

    60 

    61 

    62 

    63 Cross references

    64 ================

    65 

    66 To arbitrary section

    67 --------------------

    68 

    69 :ref:`identifier` ou :ref:`label <identifier>`

    70 

    71 Label required of referencing node which as no title, else the node's title will be used.

    72 

    73 

    74 To API objects

    75 --------------

    76 See the autodoc sphinx extension documentation. Quick overview:

    77 

    78 * ref to a class: :class:`cubicweb.devtools.testlib.AutomaticWebTest`

    79 

    80 * if you can to see only the class name in the generated documentation, add a ~:

    81   :class:`~cubicweb.devtools.testlib.AutomaticWebTest`

    82 

    83 * you can also use :mod: (module), :exc: (exception), :func: (function), :meth: (method)...

    84 

    85 * syntax explained above to specify label explicitly may also be used