GSoD Project Report - Documentation for Basic Modules

[dave (David Harper)]

Project Report

The documentation development phase of the 2020 Google Season of Docs has now ended.

Here you can find a description of what work was completed for the Documentation for Basic Modules project, and also links to the current state of this documentation and to topics and posts that were related to the project.

As the project progressed the GSoD Project - Documentation for Basic Modules topic kept track of the main progress and helped refine the project plan. It also gave people an initial place where they could provide feedback and comments on the proposal.

Work Completed

I created final drafts of improved documentation for Tryton’s basic modules.

Tryton was missing a Style Guide for its documentation, so I proposed one. This then evolved as the documentation was written, and feedback was obtained. This should help people who are writing future documentation, and help keep the documentation consistent.

As well the ongoing help and advice from the project mentors we also got together towards the middle of the project for a virtual meeting. This was a good opportunity to evaluate the progress so far, decide what changes were required, and possibly look at extending the scope of the project slightly, as long as time allowed. The GSoD Status update topic let everyone know how things were going.

The status update provided valuable feedback, and it became clear it would be easier for some people to read and review the documentation if it was in the final rendered format. Based on this I duplicated the structure of https://docs.tryton.org/ and setup a preview of documentation at https://tryton-gsod.readthedocs.io/ which was used to preview the work and how it looked, and will be removed once the documentation has been committed.

As Tryton is modular, each module is a separate project on readthedocs, so I also proposed and discussed a way of adding Links in the Documentation between modules. This was then integrated into the style guide.

As the early draft versions of the module documentation got created people had the opportunity to read, review and comment on them. These comments, along with the style guide and the discussion in the status update meeting allowed me to edit and improve the early drafts and work towards the final drafts.

During the status update meeting we discussed what additional modules could be documented if there was time after the documentation had been edited to final drafts. Out of the two additional modules that were mentioned there was time to create draft documentation for the res module. As this module is part of the trytond server, when working on its documentation I also fixed the server’s documentation build warnings.

Current State

At the end of the documentation development phase there are now final draft versions of the documentation that are waiting to be reviewed by the core members of the Tryton development team. There are also proposed and committed changes and fixes for things that are needed to allow the final documentation changes to be used.

The repositories that these changes target are all found at https://hg.tryton.org/.

Basic Module Documentation

There are improvements to the documentation for each of the basic modules:

• account
• account_invoice
• account_invoice_stock
• account_product
• company
• country
• currency *
• party *
• product
• purchase
• stock
• sale

And also for the res module in trytond:

• res

Note: Code reviews for the starred (*) modules already existed before the start of the project, but were edited and improved during the project.

Additional Module Documentation

In addition to the main documentation there is also a change to add help_selection to states as part of the stock module documentation improvements.

Style Guide

There is a proposed style guide ready for inclusion on the Tryton website:

• Add documentation style guide

Fixes and Other Improvements

To allow toctree directives in all the index.rst files there is a change for the Tryton module cookiecutter template, and a check to ensure the package’s long_description (which comes from the index.rst file) is valid:

• Remove toctree from README.rst files
• Add test for readme format

A few changes that fix warnings when building the readthedocs documentation:

• Mark as orphans any files not in a toctree
• Remove glossary directive

Changes to fix warnings when building the trytond documentation:

• Document One2One.get_relation method
• Replace TODO directive with comment in documentation

And to use double backticks for all literal values in trytond documentation.

Challenges and Learnings

It was difficult to get Tryton users to provide feedback on what I had written. Some of this may have been due to the fact that the documentation changes were on codereview.tryton.org.

Creating a preview of the documentation helped a little, but it would have been good to have got more comments and suggestions from a wider range of users with different experience levels with Tryton.

During the documentation writing process I learned a lot about how the basic Tryton modules are structured and how they work, and it’s interesting to know that even people who have been working on Tryton for years are still learning new things about it. Hopefully some of that knowledge has been distilled into the documentation that I wrote.

While researching what things to include in the usage section of the documentation I found it useful to search through the discuss.tryton.org forum for common user questions. It can sometimes be difficult to predict what issues new users will encounter especially when seemingly trivial things stop them in their tracks.

I now have a much deeper understanding of reStructuredText, and also what’s considered best practice when documenting Python and Python code.

Overall I found it great to work with, and more importantly learn from, such an amazing group of dedicated and knowledgeable people.