Links in the Documentation between modules

Feature Ideas
1

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.

To allow the use of these links between the different modules, and to do so in a way that is both maintainable and more readable I would like to use both intersphinx and autosectionlabel.

If you are not aware, intersphinx and 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 tox.ini and .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.rst file in the product module was split up into design/*.rst files.
  • 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?

2

I’m missing a human readable name for the model: `product` vs Product_. Is it possible to still have a human readable string?

This is because autosectionlabel. I’m not sure it is good to rely on title to make label. Will it not be better to have our own rules and define meaningful labels ourself?
Because for me we could change easily a title without notice it was used as label.

I guess it could be put in doc/ folder?
Should not variable that are not sphinx configuration be marked as private or not put in the global context?

3

Yes, can be done with:

`Unit of Measure <product.uom>` instead of `product.uom`
4

Sorry, pressed reply by mistake before I was finished…

Actually it is because of intersphinx, autosectionlabel removed the need for the line:

.. _making-products-purchasable:

I still needed to add the anchors containing the model names, but we could also use explicit anchors for the targets like this one and not use autosectionlabel.

Yes, this was what I was thinking.

Yes, you are right, that would be much cleaner and I can certainly fix that.

5

I think it is better to be explicit because when changing a label we will care about references which is not the case when changing a title (even for a typo).

But how will it work when there will be duplicates labels across all the modules? Should not we add a prefix when making a ref to the label of a specific module?

6

Yes, we can do that. The anchor name doesn’t need to be changed. Intersphinx lets you be specific about which external project (module) you want to link to. To do this you add the project (module name) to the start of the reference, for example:

`Unit of Measure <product:product.uom>`

This will link to the .. _product.uom: target in the product module documentation.

1 Like