GSoD Project - Documentation for Basic Modules

[ced (Cédric Krier)]

@dave

In this case do you think the right place is in the help text for each selection (Issue 9649: Add help for each selection - Tryton issue tracker) of the shipment’s state field?

I think so.

@dave

I did find the ModelWorkflowGraph which I think is what you are referring to

Indeed I forgot it was already implemented. But it will be helpful if it was available automatically as a report on any record with a workflow.

@dave

I don’t think this should be directly inserted in to the module documentation because it can change depending on what modules are activated.

Neither, just like we do not repeat help text in documentation we should not repeat workflow graph.

[dave (David Harper)]

@ced

Indeed I forgot it was already implemented. But it will be helpful if it was available automatically as a report on any record with a workflow.

I agree, at the moment you have to open the report from the Administration → Models → Models menu item, so it is not too easy for a normal user to get hold of it.

I’ve create Make the Model Workflow Graph available from records that have Workflows (#9691) · Issues · Tryton / Tryton · GitLab for this.

@ced

@dave

In this case do you think the right place is in the help text for each selection (Issue 9649: Add help for each selection - Tryton issue tracker) of the shipment’s state field?

I think so.

When issue9649 is done, do you also think it might be a good improvement to include any help text from the state field selections in the Model Workflow Graph too? Perhaps as small text under the state name, using HTML-Like Labels?

[ced (Cédric Krier)]

@dave

When issue9649 is done, do you also think it might be a good improvement to include any help text from the state field selections in the Model Workflow Graph too? Perhaps as small text under the state name, using HTML-Like Labels ?

Maybe if it does not bloat too much the graph.

[pokoli (Sergi Almacellas Abellana)]

@ced

@dave

I did find the ModelWorkflowGraph which I think is what you are referring to

Indeed I forgot it was already implemented.

I think it should be improved to make it more user friendly as it currently only shows the internal names of the transitions and the models. If we plan to show this to the end user it should use the user language for model name and selection options.

Maybe we should have two reports: One for developers from Models menú and other for users from the workflow button.

[ced (Cédric Krier)]

I’m writing documentation for a new module following the new format.
I need to document a scheduled task that user must define. I’m wondering where should it go? My first idea is to put it under usage.rst.

[dave (David Harper)]

If it is a scheduled task that the user needs to create then I think usage.rst is probably a good location for it.

Another alternative is setup.rst, but that is intended to be used for things that need to be setup before the module will work, and I think very few scheduled tasks (by their nature) would fit into that category.

I think it is unlikely that it needs to be directly mentioned in the design.rst.

The idea is that in either of those files you would have a section with a title such as “Scheduling something to happen”, or maybe “Automatically updating something”, and it would describe what the user needs to do to accomplish that (often with links to the various models and wizards that may be involved).

[pokoli (Sergi Almacellas Abellana)]

@ced

I need to document a scheduled task that user must define. I’m wondering where should it go? My first idea is to put it under usage.rst.

If this is something the user should know to use the module it should be on the usage page.

[tumashu]

by the way, what “ir” mean?

[josesalvador (José Salvador)]

I think it means internal resource.

PS -> Please evict off-topic and keep this thread for its subject. Feel free to open a new one to ask every thing you want.

[ced (Cédric Krier)]

@dave, I see that in readthedocs repository, you changed the link for a :ref:…<index-…>. I’m wondering how it will work for the different series? How will the build of this main page for series 6.0 will correctly link to the documentation of the module of the same series?

[dave (David Harper)]

@ced

I see that in readthedocs repository, you changed the link for a :ref:…<index-…>.

Would you be able to point out where that change is?

@ced

I’m wondering how it will work for the different series?

I don’t think it will. I don’t think readthedocs repository knows which version it is, so all the links need to be relative. So it’s something that I would need to fix.
Also without a conf.py file it cannot link to external documentation, as Intersphinx won’t be enabled.

[ced (Cédric Krier)]

@dave

Would you be able to point out where that change is?

Oops I miss read the index, indeed the party link is an internal reference.
So all good here.

[dave (David Harper)]

That’s good, you had me worried there!