Documentation

The project docs are published automatically to GitHub Pages on every push to a versioned branch (e.g. 18.0, 19.0) or master. To build locally:

pip install -r docs/requirements.txt
cd docs && make clean html   # output under build/html/<VERSION>/

Maintenance scripts live in docs/scripts/, are registered as file-filtered pre-commit hooks, and are called automatically by make html:

• check_flow.py — inserts line breaks after text sentences end, not after and not before (pre-commit: .rst).

• check_links.py — ensures versioned URLs in docs, code, and the README match the current git branch (pre-commit: .py, .xml, .rst, .md).

• check_python.py — keeps py:method:: signatures, py:attribute:: types, py:class:: existence, and fieldhelp:: references in sync with Python source via AST analysis (pre-commit: .py, .rst).

Each script can be called in two ways:

python3 docs/scripts/check_script.py          # rewrite RST in place (for make html)
python3 docs/scripts/check_script.py --check  # exit 1 if rewrite needed (GitHub CI)

---

Cheatsheet

Custom directives

.. manifest:: <module>

Renders version, depends, and license from addons/<module>/__manifest__.py as an inline paragraph.

.. manifest:: sync_base

Output: Version: 19.0.1.0.0 · Depends: base, mail · License: OPL-1

.. docstring:: <path> <Symbol>

Pulls a docstring from Python source via AST (no imports, no Odoo installation needed). Three forms:

.. py:class:: ip.model

   .. docstring:: addons/module/models/ip_model.py ClassName

.. py:method:: ip.model.method_name(arg)

   .. docstring:: addons/module/models/ip_model.py ClassName.method_name

.. py:function:: function_name(arg1, arg2)

   .. docstring:: gateway/module/file.py function_name

Output: the Python docstring injected as RST body under the py:method directive.

.. fieldhelp:: <path> <ClassName.field_name>

Extracts the help= kwarg from an Odoo field declaration and injects it as RST. Emits a build warning when the field has no help= argument.

* - :py:attr:`ip.model.field_name`
  - .. fieldhelp:: addons/module/models/ip_model.py ClassName.field_name

Output: the help= string rendered inline in the table cell.

.. decorators:: <path> <ClassName.method_name>

Renders the route decorators (@app.post, @http.route, etc.) that precede a method or function as a formatted annotation block. Always place before .. docstring:: inside the same directive body.

.. py:method:: Controller.endpoint(**kwargs)

   .. decorators:: addons/module/controllers/main.py Controller.endpoint

   .. docstring:: addons/module/controllers/main.py Controller.endpoint

Output: POST /api/endpoint annotation block, then the docstring body.

:repofile:

Inline role — renders a clickable link to a file relative to the repository root.

See :repofile:`docker-compose.yml` for the full service definition.

Python directives

.. py:currentmodule:: sync_base       {# sets resolution context; no index entry #}
.. module:: sync_base                 {# canonical module entry (reference files only) #}

.. py:class:: ip.model                {# Odoo model or Python class #}
.. py:exception:: ExceptionName
.. py:function:: function_name(arg1, arg2)   {# module-level / gateway function #}

.. py:method:: ip.model.method_name(arg1, arg2='default')
   :abstractmethod:                   {# optional flag #}

.. py:attribute:: ip.model.field_name
   :type: fields.Char
   :value: ''

.. py:property:: ip.model.property_name
   :type: bool

Python roles (inline)

:py:class:`ip.model`                         {# short form — resolves via currentmodule #}
:py:class:`sync_base.ip.model`               {# fully qualified #}
:py:class:`~sync_base.ip.model`              {# fully qualified, display short name #}

:py:meth:`ip.model.method_name`
:py:meth:`~sync_base.ip.model.method_name`   {# cross-module, short display #}

:py:attr:`ip.model.field_name`
:py:exc:`ExceptionName`
:py:func:`function_name`

Reference roles

:doc:`../networks/http`           {# relative path, no .rst extension #}
:ref:`guide-label`                {# named anchor: .. _guide-label:   #}
:term:`Term`                      {# glossary entry                   #}

Symbols

Prose
-----
…          ellipsis        (U+2026)
—          em dash         (U+2014)
→          right arrow     (U+2192)
←          left arrow      (U+2190)
↔          both arrows     (U+2194)
▸          menu path       (U+25B8)

Diagrams
--------

┌──┬──┐      ▲         △
│  │  │      │         │
├──┼──┤   ◀──┼──▶   ◁──┼──▷
│  │  │      │         │
└──┴──┘      ▼         ▽