A Dilluns, 20 de febrer de 2012 01:09:04, Udo Spallek va escriure: > > 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')
Thanks, didn't know this proteus feature, but one of the main goals for using those Sphinx directives is to ease translations. > 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 should be the same description, yes. > 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. Our goal is to eventually integrate [1] in tryton. So the idea is that users can access any paragraph in the docs where a field is mentioned from the field's "tooltip" itself. The same goes for views and menu entries. > 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? If we could store that information in the database, we could access them with a more generic tag as suggested by Cédric. So I'm all for anything that easies writing documentation. > > 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? That's problematic, yes. Only if tryton client used proteus :) Anyone with deeper knowledge of tryton client knows if that is easily achievable or we should find another solution? > > 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? Some inheritance examples are explained in [1], but I still have to think how that could be achieved using Sphinx only. The idea is that you should be able to *add*, *remove*, *append*, *prepend* and *replace* rst text to existing rst paragraphs. That should allow each module to provide its own user documentation. > > 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? I think the proposal on the other e-mail in answer to Cédric proposal will solve this too. [1] http://www.nan-tic.com/en/documentation-the-new-framework-explained -- Albert Cervera i Areny http://www.NaN-tic.com Tel: +34 93 553 18 03 http://twitter.com/albertnan http://www.nan-tic.com/blog -- [email protected] mailing list
