I am starting this topic to try and refine the project plan, get feedback and comments on the proposal and also to help track the progress of the project.
The aim of the project is to update the documentation for the basic Tryton modules. These are the modules that people will most commonly need to activate when setting up a Tryton system. The idea is to update the module documentation along the lines of the changes already proposed for the party module.
Please help me make this a success by letting me know what you think.
First of all congratulations for being accepted. This is a very goods news for the project.
I’m one of the mentors of this project, so my task is to help you succed on this task!
It will be great if you can create an upfront schedule for the work to do. We have until 30th of November to perform the tasks. I think it will be a good idea to organize the work into weeks effort. What do you think?
It will be great to start sharing your work ASAP so you will have early feedback, so the idea is to share a review once you have a first version of the module documentation. Also, having smaller reviews helps to speed up the review process. If we are on time, we may include some of the work as part of the next series (which is scheduled for 5th of November) and include the rest for the 6.0 series.
For me it makes sense to start documenting using the dependency order. So when you document the account module all of it’s requirements have been documented. Do you think this makes sense?
Thanks Sergi, your help and advice is very much appreciated.
Yes, this all sounds very sensible. I’ll look into how long I think it will take to update the documentation for each module, and add an estimate of when I think the first draft for each module will be ready (making sure they are in dependency order). The aim will be to get the first drafts ready fairly early in the process, so I can get early feedback. Also this should then ensure there is time to get them reviewed, proof read, edited and updated as required.
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.
