I’ve created and uploaded a review for an initial style guide: https://codereview.tryton.org/300511003/
I’m going to continue documenting things, it should be fairly easy to update the documentation to match the style guide (and any changes to it) once we are fairly happy with it.
I’m currently working on documenting the various different shipment types and stock moves. All the modules so far have not really used Workflows (except for account fiscal years and periods, whose workflow was easy to describe in a sentence).
I am aware that we do not want to define fields, or the selection values from fields, in the module documentation as it is not the right place for it. However, as I am working on documenting the design of shipments, and stock moves, it seems like it is necessary to document the workflows / states of these models to properly understand how they work and are designed.
My first thought was to add a workflow section to each models design documentation and then list the states and describe them, as is currently done in the stock module documentation, but I’m wondering if anyone else has any better ideas or suggestions.
I do not think we must document state values especially when we will have Issue 9649: Add help for each selection - Tryton issue tracker.
But I think we should focus on the workflow. So for me, the workflow is about the transitions and the action performed during each transitions. But maybe the best would be to generate a transition graph from any model with a workflow with the client (like a kind of help). Indeed I think with the previous workflow engine we had such graph generated using pydot.
Yes, this is why I was looking for a better approach.
So, are you suggesting putting the documentation for the transitions into the code, instead of the module documentation, something like:
class FiscalYear(...):
...
@classmethod
def __setup__(cls):
...
cls._transitions |= set((
('open', 'close', "Closes the fiscal year and all its periods."),
('close', 'locked'),
('close', 'open'),
))
Or perhaps using the @Workflow.transition decorator instead to add the help text,
at it is closer to the code that performs the transition?
@Workflow.transition('close', help="Closes the fiscal year and all its periods.")
Then using the cls._transitions and pydot to generate a workflow diagram that contains the “help” text for the transitions?
No for me a transition can not really be documented. Or it is always the same: “record in x state can go to y state”.
Neither this is still a transition.
At best it is the button that trigger the transition that could have help (which is already supported but not really used).
For me, we could show just the diagram with the name of the state (maybe the current state of the record highlighted) and the vertices as arrow.
So at the moment in the stock module documentation there is some really insightful and useful information about how the state of a shipment’s stock moves are related to the shipment’s state. So I am looking for the right place to put this information. In this case do you think the right place is in the help text for each selection (Add help for each selection (#9649) · Issues · Tryton / Tryton · GitLab) of the shipment’s state field?
I did find the ModelWorkflowGraph which I think is what you are referring to, but I don’t think this should be directly inserted in to the module documentation because it can change depending on what modules are activated.
I think so.
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.
Neither, just like we do not repeat help text in documentation we should not repeat workflow graph.
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.
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.
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.
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.
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).
If this is something the user should know to use the module it should be on the usage page.
by the way, what “ir” mean?
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.
@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?
Would you be able to point out where that change is?
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.
Oops I miss read the index, indeed the party link is an internal reference.
So all good here.
That’s good, you had me worried there! 