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.

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 register the directive in the setup function in your conf.py file. (This is a bug, see TODOs)

def setup(app):
    """Register the directive."""
    from sphinxcontrib_relativeinclude import RelativeInclude
    app.add_directive("relativeinclude", RelativeInclude)

Then you can use it in your documentation index under the registered name.

.. 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 repositories 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.

Module Documentation

The sphinxcontrib-relativeinclude.relativeinclude module implements the RelativeInclude class, which provides a new relativeinclude directive for reST. This directive works just like a normal include, but it will translate relative paths in the included document, so that they’re relative to the document we’re including from.

Warning

This does not support nested includes yet!

class LinkTranslator(document: document, absolute_base: Path, relative_base: Path)

Translates relative links in included documents with respect to the source document.

resolve_attrs: ClassVar[Collection[str]] = ('reftarget', 'uri'): Attributes, that need changing.

ignore_schemes: ClassVar[Collection[str]] = ('http', 'https', 'data'): If we encounter these prefixes in a link, we leave it alone.

default_visit(node: Node): When visiting a node, we change all attrs with relative paths, defined in change_attrs.

unknown_visit(node: Node): If we don’t know a Node, we ignore it.

default_departure(node: Node): Override abstract method for completeness.

class RelativeInclude(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

This class is supposed to implement a relativeinclude directive in Sphinx. It should automatically translate relative links in included documents and apart from that works just like .. include::.

resolve_attrs: ClassVar[Collection[str]] = ('reftarget', 'uri'): Attributes, that need changing.

property include_source: Path: The absolute path of the document we’re including from.

property include_target: Path: The absolute path of the document we’re including.

run() → List[Node]: Include a file as part of the content of this reST file, and translate any relative paths in the included file.

translate(node: Node, absolute_base: Path, relative_base: Path)

Recursively translate relative nodes.

Parameters:

node – The node we’re currently working on.
absolute_base – The absolute path of the file from which we are including.
relative_base – The absolute path of the file we are including.

setup(app): Register the directive.