sphinx-doc / sphinx-doc/sphinx

Support include paths outside of source tree

Open
#9,511 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.

I try to combine the architecture documentation in a sphinx project with diagrams (*.svg, *.png) generated from a model created in a MBSE tool - think of something like the EA Export in docToolchain.
I'd like to have these generated diagrams outside of the source tree.

Describe the solution you'd like

I'd like to specify additional include paths, like the Doxygen configuration allows (e.g. IMAGE_PATH).
Images should be referenceable by relative or absolute path, just like how it works for images below the source root directory.

Describe alternatives you've considered

An alternative is to have an "_images" folder in the source tree and add that to .gitignore, to avoid checking in generated images. Usually works fine, only un-supported use case is building the documentation in a docker container which mounts the source-tree as read-only volume.

Another alternative would be to write my own extension to provide this functionality via directive, e.g. ".. ea-image::" or ".. ext-image::" - only that I have no experience how to do this, and I don't know if sphinx extensions can read outside of the source tree.

Additional context

Some more people already requested this in the past, e.g. https://github.com/sphinx-doc/sphinx/issues/7772

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing Sphinx's existing image and include-path handling, then read the related prior request in issue #7772. Define how relative and absolute paths outside the source tree should be resolved, and consider the read-only Docker use case; done means external SVG and PNG files can be referenced and included reliably.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.