GSoD Project - Documentation for Basic Modules

I am both delighted, and very fortunate, that my proposal for improving the Documentation for Basic Modules for the Google Season of Docs has been accepted.

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.

The proposal is, for the files inside the doc directory to include, where required:

  • index.rst
    A basic description of the module and a table of contents.

  • design.rst
    Information about how the module is structured. Including descriptions of the models, wizards and reports it contains.

  • setup.rst
    Instructions on any additional setup that may be needed once the module has been activated.

  • usage.rst
    General guidance and instructions on the features provided by the module, and how to use them.

Please help me make this a success by letting me know what you think. :pray:

The basic modules include (in dependency order, with a current planned week commencing date for the first draft):

  1. 2020-09-14 [issue9598] country
  2. 2020-09-14 [issue9124] currency
  3. 2020-09-14 [issue9139] party
  4. 2020-09-14 [issue9601] company
  5. 2020-09-21 [issue9610] account
  6. 2020-09-28 [issue____] product
  7. 2020-09-28 [issue____] account_product
  8. 2020-10-05 [issue____] stock
  9. 2020-10-12 [issue____] account_invoice
  10. 2020-10-12 [issue____] account_invoice_stock
  11. 2020-10-19 [issue____] purchase
  12. 2020-10-26 [issue____] sale
3 Likes

Hi Dave,

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. :+1:

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.

I think we need Issue 9596: Fetch model names for when its is missing - Tryton issue tracker so we do not have to hard-code the name in the URL menu entries.

Yes, the documentation will be cleaner without needing to add the name into the URL. Thanks.

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.

1 Like