tk0miya
commented
3 years ago How about referring to them as remote images (referring by URL)? IMO, you can generate including external images.
From the perspective of Sphinx development, supporting images outside of the project directory will bring other problems. Besides images, sphinx can use many kinds of resources. Then we'll need to decide how to treat them. I feel it's a very big change to this project, and it's much simpler to add a new directive via extension. So I vote -0 for your idea at this moment.
Thank you for your proposal :-)
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