.. TryDoc Test documentation master file, created by sphinx-quickstart on Sun Nov 13 11:04:16 2011. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. 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/ 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::: Cron 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*). .. _figure directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure 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@.