Hi,
Sat, 18 Feb 2012 18:34:58 +0100
Albert Cervera i Areny <[email protected]>:
> as discussed in TUL, I've been working on a documentation framework
> for Tryton integrated in Sphinx. The idea is to create two separate
> sphinx extensions: trydoc and inheritance.
> The first one, which is the one for which I've made the first alpha
> release available,
I gave it a test, and it works as promised.
> provides directives for adding references to fields and menu entries,
This is a very cool functionality for the docs. It is even possible
to get the localized names of field and menu entries. Just use the
`language` attribute in proteus config, like for German language::
proteus.config.set_trytond(database_type='sqlite', language='de_DE')
Another good feature is the possibility to show the 'help' attribute
from the `fields` definition[4]. Inline with @field:ir.cron/user:help@.
I ask my self, if there is a difference in the help descriptions. One
help text provided as a tool tip in in the client on mouse over a
field. And the other help text provided with your sphinx extension as a
Field description in the documentation.
It would be good, if a field of a model has a tool tip and a
description in the documentation. IMHO both, tool tips and
documentation should be the same in general. If some specific additions
are needed for the documentation, they can be added like this::
@field:ir.cron/user@
@field:ir.cron/user:help@. Internal users are usually
de-activated, and needed to be explicitly searched with an
*active:False* clause.
With this we move the general documentation close to the internal
definitions, to the field code it should describe.
Additionally similar general descriptions could be provided by the
model __doc__ and _description.
What do you think about this?
> as well as generating screenshots and
> embedding them in the docs.
> You can find the project on bitbucket [1] but it is also available in
> pypi [2] among with some docs [3].
I try successful with a bitbucket[1] developer installation::
pip install -e trydoc/
> The main limitation of this release is that although it creates
> screenshots, they're not from the appropriate view.
The screen shot functionality looks promising. Do you have a
solution for the login problem, to get the appropriate view for the
screen shot? The uri handler in the Tryton client seems to miss a
feature for opening a specific tab in a view, or, - as an other
possibility, - to ensure a given field name is visible for the
screen shot?
> The other extension (inheritance), which is not yet implemented,
> should bring some inheritance mechanism to Sphinx so we can
> update/inherit documentation the same way we do with views. This
> module will have no dependency on tryton, and can hopefully become a
> sphinxcontrib extension and reused by other projects.
What would be the exact functionality for this extension?
> Of course, any help, comments or input on their syntax and features
> will be very welcomed.
Maybe it is a good idea to change the menu syntax from::
@menu:ir.menu_cron_form:nameonly@
to IMHO more intuitive::
@menu:ir.menu_cron_form:name@
What do you think about this?
> [1] https://bitbucket.org/albertnan/trydoc
> [2] http://pypi.python.org/pypi/trydoc
> [3] http://packages.python.org/trydoc/
[4] http://doc.tryton.org/2.2/trytond/doc/ref/models/fields.html#help
Albert, thank you a lot for the great enhancement!
Regards
Udo
--
_____________________________
virtual things
Preisler & Spallek GbR
München - Aachen
Windeckstr. 77
81375 München
Tel: +49 (89) 710 481 55
Fax: +49 (89) 710 481 56
[email protected]
http://www.virtual-things.biz
--
[email protected] mailing list
