sphinxcontrib-relativeinclude

About

This package implements a new reST directive to include files and translate paths included in those files.

Installation

The project is hosted on PyPI, and can be installed via pip.

pip install sphinxcontrib-relativeinclude

You can find the contents of the README and the module documentation for the latest release online. It's also available PDF or EPUB.

Motivation

Let's assume you want to transclude the README.rst sitting in your repository root, in your docs/index.rst, so it automatically shows up in your generated documentation. You can just use reST's standard include directive.

.. include: ../README.rst

Sidenote: If you're using a parser, like MyST, you could also easily include markdown files, of course.

This will insert the contents of your README in the appropriate place, and even take care of heading levels for you.

The problem arises when you have images or other files included in there. Sphinx won't resolve those links properly, i.e., relative to the README, but instead relative to your Sphinx index document. That means those pictures won't show up, which, needless to say, is not optimal. If you use your valuable time to create visual resources for your documentation these should also be included in the documentation output.

Picture of a honey badger by Sumeetmoghe on Wikimedia Commons (CC-BY-SA-4.0)

This picture uses a relative path to a file in the docs/assets directory, and would happily show up in your Git repo, but not in your documentation.

This is what this extension is supposed to solve. It defines a new relativeinclude directive, that takes relative paths in included files, and resolves them into absolute ones. This way your images show up in your documentation output, but you don't have to hardcode absolute paths in your documentation. (Cf. this awesome honey badger here)

Caveat emptor: At this point in time, nested includes are unfortunately not supported. (See TODOs)

Usage

You have to enable the extension in your conf.py file.

# in conf.py
extensions = [
    # ...
    "sphinxcontrib.relativeinclude",
    # ...
]

After that, the directive will be available for you to use in your documentation.

.. relativeinclude: ../README.md
    :parser: myst_parser.docutils_

It supports the same options as the standard include directive. If not, you've found a bug, and I'd be happy if you reported it on the issue tracker. Please provide thorough description, and a minimal reproducible example, i.e., (abbreviated) reST files you used, potentially your conf.py contents and maybe other relevant info.

If you want to see some real code, check out this repository's documentation at docs/index.rst.

TODOs

• support multiple levels of indirection
• properly register directive on install

License

sphinxcontrib-relativeinclude is distributed under the terms of the MIT license.