1

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?

mzjn
  • 48,958
  • 13
  • 128
  • 248
Wasserwaage
  • 208
  • 1
  • 3
  • 10
  • 1
    There might be someone with more experience to give you an answer. What I found so far is to deploy each component to its own site and then use a reverse proxy to bridge the URLs together (for https://www.pysnmp.com). – Lex Li Nov 22 '22 at 18:28
  • 2
    A fairly complex example of what we do in Plone can be found at https://6.dev-docs.plone.org/contributing/setup-build.html and you can skip the step for PyEnchant. This repo pulls in three others via git submodules and `make`. It's pretty nifty. – Steve Piercy Nov 23 '22 at 07:50

1 Answers1

2

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
  1. trigger another build on Read the Docs and it will hopefully work :)

Let me know if that works.

Manuel Kaufmann
  • 346
  • 1
  • 7