Create single Sphinx documentation page on readthedocs.org from multiple Python repositories

Question

I have an open source project split into different repositories, which I would like to document on a single readthedocs page (using, for instance, sphinx.ext.autosummary). For now, the Sphinx conf.py and the master toctree document are contained in a separate docs repo:

docs
├── index.rst
├── conf.py
└── ...
foobar
├── foo
│   └── __init__.py
└── bar
    ├── __init__.py
    └── baz
        └── __init__.py

Building the Sphinx documentation locally, I could simply download all repositories and use relative paths to direct Sphinx to the different repositories, e.g.:

sys.path.insert(0, os.path.abspath('../foobar'))

However, this won't work building the project at readthedocs.org. I searched, but found only one solution that "(copies) all of the packages within the repo to a temporary folder, which will allow the docstring tool to scan and then generate the relevant docs." In a variation of this, symlinks are to be used.

This is likely not the optimal solution. Am I missing some basic functionality of Sphinx?

Answer 1

You can use the Read the Docs configuration option submodules to pull down other Python repositories and use the same trick sys.path.insert that you commented when building locally.

So, you would need to:

1. add the git submodule via git submodule add https://github.com/me/project/
2. commit and push the changes
3. use submodule option in Read the Docs configuration file (see https://docs.readthedocs.io/en/stable/config-file/v2.html#submodules)

version: 2

# ...

submodules:
  include: 
    - project

4. trigger another build on Read the Docs and it will hopefully work :)

Let me know if that works.