doc/dev/documenting.txt
author Denis Laxalde <denis.laxalde@logilab.fr>
Tue, 22 Dec 2015 09:23:00 +0100
changeset 11144 fd8bf29ed00e
parent 10495 5bd914ebf3ae
child 12792 e2cdb1be6bd9
permissions -rw-r--r--
[tox] Generate test environments for Python 2.7 and 3.4 Test commands for each environment are written down explicitly since I could not find a way to extract the "package" name (e.g. "hooks") from the environment name (e.g. "py34-hooks"). For Python 3.4 interpreter, only environments (subpackages) that do not depend on cubes for their tests are listed since those test dependency cubes are not yet installable with Python 3.x. etwist is also not included since the Python 3 port is not complete at the moment. From local testing, py34 tests pass for the following subpackages: - dataimport - entities - ext - hooks - wsgi

====
Book
====

----
Part
----

Chapter
=======

.. _Level1AnchorForLaterReference:

Level 1 section
---------------

Level 2 section
~~~~~~~~~~~~~~~

Level 3 section
```````````````



*CubicWeb*


inline directives:
  :file:`directory/file`
  :envvar:`AN_ENV_VARIABLE`
  :command:`command --option arguments`

  :ref:, :mod:


.. sourcecode:: python

   class SomePythonCode:
     ...

.. XXX a comment, wont be rendered


a [foot note]_

.. [foot note] the foot note content


Boxes
=====

- warning box: 
    .. warning::

       Warning content
- note box:
    .. note::

       Note content



Cross references
================

To arbitrary section
--------------------

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

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


To API objects
--------------
See the autodoc sphinx extension documentation. Quick overview:

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

* if you can to see only the class name in the generated documentation, add a ~:
  :class:`~cubicweb.devtools.testlib.AutomaticWebTest`

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

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