[PDF build] Build a documentation site per subproject

[dgarcia360]

The repository contains several Sphinx subprojects. However, all of them are published as a single site.

ReadTheDocs provides a feature to work with multiple projects more effectively:

Projects can be configured in a nested manner by configuring a project as a subproject of another project. This allows for documentation projects to share a search index and a namespace or custom domain, but still be maintained independently.

For example, a parent project, Foo is set up with a subproject, Bar. The documentation for Foo will be available at:
https://foo.readthedocs.io/en/latest/
The documentation for Bar will be available under this same path:
https://foo.readthedocs.io/projects/bar/en/latest/

RTD Subprojects feature would let you:

• Build separate PDF builds per project (e.g., one for each user manual).
• Version each subproject differently.
• Have faster builds since the whole project does not have to be rebuilt every time, only the subproject that received an update.

Limitations

⚠️If you decide to support RTD Subprojects, building a single PDF / HTML site locally that includes all the subprojects documentation will not be possible. Instead, you will have to build each site independently.

Proposal

For every subproject:

1. Create a new project on ReadTheDocs.
2. Enable PDF builds (optional).
3. Look for cross-references to other projects, and fix them.

In the main project:

1. Remove the subprojects from the toctree.
2. Add links to the subproject documentation.
3. Create 404 redirections for every page moved from the main project.

In the theme:

• Customize the theme to link to the parent documentation from subprojects. This feature not provided by the theme you are using yet (Add a link back to the parent project in subprojects readthedocs/sphinx_rtd_theme#1000)

ℹ️ This proposal affects substantially the current navigation structure . Therefore, before implementing this solution in production I would share with you a Proof of Concept on a staging site moving one subproject to show you how the resulting documentation site would look like.