TryDoc documentation¶

Installation¶

This extension requires the following packages:

Sphinx >= 1.2
proteus 3.2.x
path.py
tryton 3.2.x (optional if you don’t need view directive)

Use pip to install this extension straight from the Python Package Index:

pip install trydoc

Configuration¶

In order to use trydoc you should add it to the list of extensions in conf.py:

extensions = ['sphinxcontrib.trydoc']

You should also configure proteus in conf.py with the required parameters. The following example will create a new sqlite database automatically:

import proteus
proteus.config.set_trytond(database_type='sqlite')

If you use ‘sqlite’ memory database (like the example) you must define the list of modules to install to be able to reference their elements (models, fields, views, menus...).:

trydoc_modules = ['party', 'sale']

You can use a persistent PostgreSQL database (the customer’s database tipically). The configuration will be something like this::

proteus_config = proteus.config.set_trytond(database_name='trydoc',
        database_type='postgresql', language='es_ES', password='admin',
        config_file='~/trytond/etc/trytond.conf')

Tryton Documentation project: Provided Scripts¶

If you want to prepare an User and/or Administrator manual, this packages provide some useful scripts to prepare and mantain it.

It have some extra requirements:

sphinxcontrib-inheritance: another Sphinx extension (available on PyPI) that provides inheritance funcionality. It’s used to compile the documentation in modular way.
trytond-doc: project with the documentation of Tryton’s core (server, client and core modules) available on Bitbucket.
Third party modules sources: each module should include its own documentation in doc/<language> directory.

The provided scripts:

trydoc-quickstart: as sphinx-quickstart it helps you to prepare a new Sphinx project. Based on the answers during the script execution, it will leave the conf.py and other required files prepared.
trydoc-symlinks: put into the documentation project directory required symlinks to the language specific documentation of Tryton modules.
trydoc-update-modules: trydoc-quickstart prepare conf.py to get the trydoc_modules from modules.cfg. This script upates this file with the installed modules in specified Tryton database.

If you don’t want to include the base documentation from trytond-doc project, you should customize the index.rst file generated by trydoc-quickstart scripts.

Usage¶

TryDoc adds the following set of directives to be used in the docs:

Model¶

You can refer to any model with the following directive:

.. model:: model.name

which will print the given model name inside an _span_ with the class trydocfield. You can change this default class with the configuration option trydoc_fieldclass.

Optionally the :info: flag can be added to get the Info field of ir.model. It isn’t translated so provably it isn’t very useful:

.. model:: account.tax
   :info:

It also have another optional option :class: CLASSLIST. It adds the specified classes to the _span_ (not replace the default class). An example::

.. model:: ir.cron
   :class: admin

It will generate the following code::

<span class="trydocmodel admin">Cron</span>

Field¶

You can refer to any field with the following directive:

.. field:: model/field

which will print the given field name inside an _span_ with the class trydocfield. You can change this default class with the configuration option trydoc_fieldclass.

Optionally the :help: flag can be added. See the following example:

.. field:: ir.cron/user
   :help:

It will print the help text of field despite of the field name (if the field doesn’t have help text it will print a message advertising it.

It also have the optional option :class: CLASSLIST.

Tryref¶

To show any data introduced in a XML file you can use the tryref directive.

You can refer to any menu entry with the following directive:

.. tryref:: reference_to_menu_xml_id/fieldname

The following code shows the full menu entry:

.. tryref:: ir.menu_cron_form/complete_name

which will output Administration / Scheduler / Scheduled Actions. You can also access any field of the record, for example:

.. tryref:: ir.menu_cron_form/name

will output Scheduled Actions. tryref can be used to access any field of any record with an ir.model.data if you know its XML id.

Like field directive, it will output the text inside an _span_ tag with the class trydocref. This default class could be changed with the configuration option trydoc_refclass. And if you want to add another classes to an specific entry you could use the :class: CLASSLIST option.

View¶

You can add a screenshot of any model view with the following directive:

.. view:: reference_to_view_xml_id
   :field: fieldname
   :show_menu: menu_xml_id
   :domain: [CLAUSES]

where :field: is optional and will ensure the given field name is shown in the generated screenshot.

.. view:: party.party_party_form
   :field: name

and :show_menu: is another option which toggle, for this screenshot, the menu to make it visible (by default, it is closed) and it expand the menu to show the specified menu item (it doesn’t close previous opened menus).

and :domain: option must to be a valid Tryton domain. It will be appended to the URL to open the propper window what will force the values of fields in domain.

Warning

All values in the domain must to be in quotes, even True/False.

It also has all options of figure directive: alt, height, width, scale, align, name, target, class... the :class: CLASSLIST option adds the specified class to the default class trydocview (which can be changed with the configuration option trydoc_viewclass).

Inline usage¶

Inline usage is also available either using Sphinx’s replace mechanism. As it uses the directive it has all options and the same behaviour than directives:

This is a reference to field |cron_user|.

.. |cron_user| field:: ir.cron/user

or one provided by trydoc, which is shorter (but it doesn’t put the text inside and _span_ tag and it doesn’t support any option):

This is a reference to a field @field:ir.cron/user@.