Sphinx docs / RST include file from dynamic path?

Question

I'm wondering if it's possible to use a dynamic path in a Sphinx and/or RST ..include:: directive?

My reason for this is I have some developer documentation generated by Sphinx in one repo, but we have a bunch of unit tests in another repo that we want to include in the docs. If I know the path to the file in the other repo, it's pretty standard, like this:

Some text in my RST file

.. include:: ../path/to/other/repo/file.py
:code: python

Some more text

The problem is the relative path to the other repo is not always the same, depending on how things are cloned and installed. For example, on Read The Docs, the other repo is installed in editable mode via requirements.txt into a /src subfolder, locally the repo is in a git folder, etc.

I can add logic into the conf.py file to find the other repo and set a pointer which I can use in the RST files, but I can't figure out if it's possible to have a dynamic path in the ..include::?

So far the only workaround I can think of is to have my conf.py find the other repo and create a symlink which I reference in the RST files, which is fine, but I wonder if there's a better way?

Brian Madden Brian Madden · Accepted Answer · 2017-07-14T21:30:23

After playing with this more for a bit, I decided that creating a soft link is the way to go. (At first I was going to use a hard link, but creating that fails on Read The Docs. Soft link works on RTD and in Sphinx.)

So I have code in conf.py that walks the folder structure to find the other repo I need to include files from, then it creates the link (after first removing the old one and checking the version of the repo it found to make sure it's the right one). Then I just do the ..include:: with the soft link and everything is fine.

So overall not a bad solution, and most importantly it works locally and on RTD, and it works regardless of the location of the other repo.

Sphinx docs / RST include file from dynamic path?

1 Answers