As each module in Tryton is documented separately, and most of the modules depend on other modules, it can very useful for the reader to have a link to concepts from other modules when they are reading the module documention.
If you are not aware,
autosectionlabel are standard sphinx extensions and can be used with readthedocs. They are designed specifically to make it easy to link to things in both the current project and other projects.
To be able to use these extensions we would need to add a
conf.py file to the
doc directory in the module. I understand that there are valid concerns that this will make the modules harder to maintain. However, just like the
.drone.yml files, the
conf.py file will be identical in each module.
For example, this:
.. _making-products-purchasable: Making products purchasable =========================== Before you can add a Product_ to a :ref:`purchase.purchase` it must be marked as purchasable. When you do this you will also be able to set some extra properties such as the `Unit of Measure`_ the product is normally bought in. .. _Product: https://tryton-gsod.readthedocs.io/projects/modules-product/en/latest/design.html#product .. _Unit of Measure: https://tryton-gsod.readthedocs.io/projects/modules-product/en/latest/design.html#product-uom
Could then be written as this:
Making products purchasable =========================== Before you can add a `product` to a `purchase.purchase` it must be marked as purchasable. When you do this you will also be able to set some extra properties such as the `product.uom` the product is normally bought in.
Which I think is more maintainable:
- It is shorter - 6 lines instead of 11.
- Links to things inside and outside the module are written in the same consistent way.
- There are no urls which may need to be changed if, for example the
design.rstfile in the product module was split up into
- Links to other modules will be for the same version as the module they are coming from. So the documentation for the 5.4 series will link to other modules documentation in the 5.4 series, instead of to the latest version.
- When writing the documentation you don’t need to know which module, or file, the model has been documented in, just its model name.
- If the target of the link cannot be found in the other project a warning is raised when building the documentation.
I have built these and added them as a temporary example to:
I don’t think the html links look as nice when using intersphinx, but it does make it easier to write the documentation, and ensure the links work.
For anyone who is interested this is the conf.py that was used, it will need to be changed slightly for use in the modules, but then it can be the same in every module.
What do you think?