8

I am new to Sphinx and would like to show the same figure in two different *.rst files.

The first *.rst file "lower.rst" is on the same level as the "figures" folder and I am including a figure in it like this:

.. figure:: figures/figure1.png

The second *.rst file "higher.rst", is several levels higher than lower.rst. In fact, I am including lower.rst in higher.rst like this:

.. include:: relative/path/to/lower.rst.

Unfortunately, in the higher.rst, the figures from lower.rst are not displayed:

"image file not readable" error.

higher.rst looks in the current directory for the figure instead of pointing to the original lower directory.

This question is sort-of addressed here: Can sphinx link to documents that are not located in directories below the root document?, but I still do not understand how to resolve my problem with the information given there.

Community
  • 1
  • 1
anfho
  • 131
  • 1
  • 9

1 Answers1

7

Put your figures in a directory at the root level, and change your markup to find them relative to the root using a leading /.

.. figure:: /_static/figure1.png

Now from the higher level file, you should be able to include the lower, and both files should display the image.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • One follow-up question, though: Is there a way to avoid the duplicate label warning for the figures? – anfho May 08 '17 at 02:44
  • I assume your included file is read as a regular reST document since it matches a value in `source_suffix`. You can either change the suffix (for example, `my_included_file.inc`) or add a pattern matching it to `exclude_patterns` in your `conf.py`. – Steve Piercy May 08 '17 at 06:07
  • yes, my included files are regular *.rst files. When changing the suffix, however, then the lower *.rst file is not included in the toctree anymore: `WARNING: toctree contains reference to nonexisting document u'/path/to/file/file_name'`. So, as a quick, but maybe not-so-clean hack, I could copy the *rst file as an *inc file and put that one in the include path? – anfho May 29 '17 at 03:13
  • Not sure how an exclude pattern would look like for two identical documents that are included in the toctree, but have different suffixes? – anfho May 29 '17 at 03:28
  • In my last comment, I should have said "same suffixes" – anfho May 29 '17 at 13:07
  • If I understand your question correctly, `exclude.rst` and `exclude.inc` could be excluded by the pattern `exclude.*` – Steve Piercy May 29 '17 at 17:28
  • Hmm. I have a lot of files that are at the lower path locations, which I want to also have at the top level path locations with the include statement. I can certainly put every single file name into the exclude pattern (which is what the `exclude.*` does: `exclude_patterns=[exclude.*]`, correct?) but I was wondering if there was a smarter way to do this? If I exclude both the `*.rst` and the `*.inc` files (which is what `exclude.*` also does, correct?), then none of them will be recognizable for the toctree? Or am I wrong here? – anfho May 30 '17 at 12:15
  • Are you suggesting then that it is a good solution to have a copy of each `*rst` file as `*inc` file? But if I choose to only exclude one of them `exclude_patterns=[*.rst]` or `exclude_patterns=[*.inc]` will the excluded file then be recognized in the toctree? - I am guessing not. – anfho May 30 '17 at 12:15
  • More examples are in the [documentation for exclude_patterns](http://www.sphinx-doc.org/en/stable/config.html#confval-exclude_patterns). – Steve Piercy May 30 '17 at 16:31