Taking :include: or rst_prolog into account for RST rendering
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Problem to solve
For larger Sphinx based documentation projects it is nice to have a common set of (inline) images to be defined either in conf.py (in rst_prolog property) or via a :include: directive holder all 'common' images. For Sphinx that is fine. But gitlab currently renders the images in rst only possible if these :image: directive is defined in the local rst file where it is used.
Intended users
Every project using Sphinx as documentation tool and willing to reuse image definitions AND those being rendered in gitlab preview
Further details
For our opensource project QGIS.org we use Sphinx rst files to write documentation, see: https://gitlab.com/rduivenvoorde/qgisdoc for a gitlab trial and https://github.com/qgis/qgis-documentation and (translated via transifex) html version: https://docs.qgis.org/2.18/en/docs/user_manual/
We already instruct doc writers to edit directly on gitlab/hub, but one thing which is not going very smoothly is the rendering of inline images (the little icons in the text for example).
RST needs these :image: directives for it.
For sphinx it is OK to define them outside 'current rst file' in conf.py (as rst_prolog or rst_epilog) OR in a separate file to be included using the :include: directive [0].
BUT gitlab just does not use these options to render images from the image-substitutions in the html/preview.
Proposal
So it would be cool if gitlab either
-
'finds' the conf.py in a sphinx-rst project and uses the substitutions from rst_prolog and rst_epilog for rendering
-
complies with the :include: directive (so we can have one file to hold all 'common' image directives see http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment
Permissions and Security
?
Documentation
What does success look like, and how can we measure that?
I can create a small sphinx project in which the images are defined in either a separate file or conf.py?