Decentralize the documentation among subprojects

[spd-intermodalics]

Unifying in a decentralized way

This project is a new very good approach to gather all documentation related to Orocos together in: Orocos documentation.

What then?

Now, the documentation is presented together is good, but if the source of the documentation is decentralized in the different subprojects, it would be even better.

How can it be done?

There is a chance to move parts to other repositories. For example, we could move all rtt content to the rtt actual repository in the docs folder, and move all the ocl documentation to that repository, and keep here what doesn't belong anywhere else.

• The first tool is intersphinx, that allows to declare remote documentation addresses and link pages very easily with only a prefix for the site name.
• Readthedocs can be configured to mount other respositories as subprojects of the main repository.

The main difficulty is to generate the table of contents that is shared in common for the side bar navigation. This documentation site is an example of it.
The developer explains a bit of the technique behind that.

• An example can be found in his documentation repository.