[debian] build the book with no auto-compression of book files (closes: #1906581)
Book content paths (html and rest) are now excluded from Debian compression step.
This will fix a documentation search issue on the website (doc.cubicweb.org)
Documentation build is now made optional since it can break for old distributions
and we don't want to block a new release of Cubicweb because of documentation issues.
====
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