There are no predefined sets of characters to use for the Headings levels in Restructure Text. However it would be great to make sure that in the module documentation it is consistent. One suggestion I received is to use https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#headings?
For the records, these are:
#, with overline, for parts (this would be the module title in the index.rst file)
*, with overline, for chapters (this would be the titles in the other .rst files)
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs
I personally don’t think we need the overline for the parts or chapters, but I am happy to use it if everyone thinks it would be better?
Hello Dave,
congratulations for being accepted!
For me the suggested heading styles are very well, because the Python documentation style guide uses the same.
For me this is depending on the surrounding text structuring. But anyway it sounds good to me to have some unused levels above and below the module documentation structure.
I am just looking at documenting the account.account model, and I can see there is a taxes field. To understand how things fit together, so I can properly document things, I am trying to understand how and where it gets used. The current documentation says
Taxes: This list of tax auto-complete move with new moves lines
corresponding to thoses taxes if the user create a line linked to
the current account and if the journal type is Expense or Revenue.
Which I kind of follow, but cannot seem to find where this happens in the code.
If someone can point me in the right direction that would be great, thanks.
I’ve just uploaded a review for the first draft of the updated account module documentation. I have also updated the other reviews so they have a fairly consistent style.
In order to try and keep this style consistent, I’ve updated the first post of this topic with a basic style guide:
It would be great if someone with a bit of time could have a quick look at the reviews so far and point out anything that they think needs to be changed.
Yes, unfortunately that’s right. To do any cross module linking you either need to use a sphinx extension such as intersphinx or provide the full url to the target (which having standard anchors may help with).
Thanks for spotting that, it’s a typo in the style guide.
I can’t find anywhere in the readthedocs documentation that specifically states what roles are supported. However, they are standard sphinx roles, and readthedocs does link directly to the sphinx documentation. Also the sphinx-rtd-theme demo does include many of them to show how they are rendered. So I think they should be fine to use?
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 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.
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?
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.
