sphinx-doc / sphinx-doc/sphinx
Support include paths outside of source tree
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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