doc/dev/documenting.txt
author Philippe Pepiot <philippe.pepiot@logilab.fr>
Thu, 05 Mar 2020 10:41:14 +0100
branch3.26
changeset 12905 fb6aecd654a3
parent 10495 5bd914ebf3ae
child 12792 e2cdb1be6bd9
permissions -rw-r--r--
[pkg] version 3.26.16
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
====
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
Book
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
====
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
----
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     6
Part
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     7
----
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     8
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     9
Chapter
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    10
=======
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    11
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    12
.. _Level1AnchorForLaterReference:
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    13
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    14
Level 1 section
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    15
---------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    16
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    17
Level 2 section
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    18
~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    19
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    20
Level 3 section
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    21
```````````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    22
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    23
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    24
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    25
*CubicWeb*
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    26
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    27
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    28
inline directives:
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    29
  :file:`directory/file`
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    30
  :envvar:`AN_ENV_VARIABLE`
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    31
  :command:`command --option arguments`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    32
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    33
  :ref:, :mod:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    34
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    35
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    36
.. sourcecode:: python
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    37
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    38
   class SomePythonCode:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    39
     ...
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    40
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    41
.. XXX a comment, wont be rendered
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    42
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    43
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    44
a [foot note]_
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    45
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    46
.. [foot note] the foot note content
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    47
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    48
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    49
Boxes
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    50
=====
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    51
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    52
- warning box: 
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    53
    .. warning::
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    54
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    55
       Warning content
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    56
- note box:
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    57
    .. note::
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    58
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    59
       Note content
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    60
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    61
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    62
6245
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    63
Cross references
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    64
================
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    65
6245
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    66
To arbitrary section
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    67
--------------------
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    68
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    69
:ref:`identifier` ou :ref:`label <identifier>`
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    70
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    71
Label required of referencing node which as no title, else the node's title will be used.
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    72
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    73
6245
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    74
To API objects
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    75
--------------
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    76
See the autodoc sphinx extension documentation. Quick overview:
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    77
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    78
* ref to a class: :class:`cubicweb.devtools.testlib.AutomaticWebTest`
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    79
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    80
* if you can to see only the class name in the generated documentation, add a ~:
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    81
  :class:`~cubicweb.devtools.testlib.AutomaticWebTest`
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    82
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    83
* you can also use :mod: (module), :exc: (exception), :func: (function), :meth: (method)...
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    84
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    85
* syntax explained above to specify label explicitly may also be used