2

I have a README.rst file which I render with Sphinx. In that .rst file I see the following two lines at the end:

.. substitutions
.. |banner| image:: docs/source/logo/Banner.png

I tried to find out what the phrase .. substitutions mean, but I did not find anything.

If I remove the line .. substitutions the sphinx command gives a warning

Problem with "end-before" option of "include" directive:
Text not found.

and the page is not rendered.

Any ideas where to find proper documentation on that directive, and what this error message means?

Google search did not help. For the error message I found 3(!) hints only.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Alex
  • 41,580
  • 88
  • 260
  • 469

1 Answers1

2

In these two lines

.. substitutions
.. |banner| image:: docs/source/logo/Banner.png

The first line is just a comment.

Comments

Arbitrary indented text may be used on the lines following the explicit markup start. To ensure that none of the other explicit markup constructs is recognized, leave the ".." on a line by itself:

But the second line is not a comment, it would have to be inside the indented block.

+-------+----------------------+
| ".. " | comment              |
+-------+ block                |
        |                      |
        +----------------------+

Having said that, you are using an .. include:: directive somewhere in your reST that apparently uses the end-before option. By removing the .. substitutions comment you are probably removing the text used in the end-before option. See this excellent answer.

Directive Type: "include" - reStructuredText Directives.

end-before : text to find in the external data file Only the content before the first occurrence of the specified text (but after any after text) will be included.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
  • Yes, I just figured that out. I just found the :end-before: directive. But without knowing that, it is impossible to understand what is going on. – Alex Feb 23 '21 at 13:19
  • @Alex This error can be confusing because happens on a different line where the `.. include::` directive is. What's worse the comment seems like a reST keyword or directive but is just a textual occurrence. – bad_coder Feb 23 '21 at 13:26