[Docutils-develop] [docutils:bugs] #459 Invalid circular inclusion warning when including multiple documents from a directive

[Günter M. <mi...@us...>]

`insert_input()` is an undocumented (internal) auxiliary method. 
Maybe the custom directive can subclass or call `directives.misc.Include` instead.

Just emptying  the document's `include_log` breaks the detection of circular inclusions :( 
(You will only recognise this in CI, if there are test cases that have both, the custom directive and a circular inclusion.)

Checking the test example file, I realized that it reports:
~~~
file1.rst:1: (WARNING/2) circular inclusion in "include" directive:
file1.rst
> file1.rst
~~~
i.e. the inclusion detection assumes that "file1.rst" includes itself recursively!
This is due to a wrong usage of `state_machine.insert_input()`: 
the line written by `DirectiveThatIncludes.run()` will (when parsed) include the source "name", but it is not from source "name".  With
~~~
    def run(self):
        name = self.content[0]
        source = self.state_machine.input_lines.source(
            self.lineno - self.state_machine.input_offset - 1)
        self.state_machine.insert_input(
            ['.. include:: %s' % name], source)
        return []
~~~
there is no warning (because, the inclusion of "file1" and "file2" uses the stock `misc.Directive`class that handles circular inclusion detection fine).
Even when using
~~~
    def run(self):
        name = self.content[0]
        with open(name) as f:
            lines = f.read()
        self.state_machine.insert_input(lines, name)
        return []
~~~
the circular-inclusion warning does not  appear here.


---

** [bugs:#459] Invalid circular inclusion warning when including multiple documents from a directive**

**Status:** pending-works-for-me
**Created:** Thu Oct 20, 2022 10:30 PM UTC by Ian Wienand
**Last Updated:** Thu Oct 27, 2022 08:34 PM UTC
**Owner:** nobody
**Attachments:**

- [circular-ref-bug.py](https://sourceforge.net/p/docutils/bugs/459/attachment/circular-ref-bug.py) (1.2 kB; text/x-python)


The recent sphinx release has found what I think is a problem in the circular-reference detection in docutils.

We have a situation where we build a page with a directive that automatically includes a file (readme from a sub-component).  In some cases, these readme's might then also include another file (e.g. similar components share a common file about their arguments, etc.).  So we have a include hierarchy like

~~~
 .. include:: ./component/README.rst
   .. include:: common.rst
.. include:: ./component2/README.rst
  .. include:: common.rst
~~~

Our directive works by reading the `README.rst` file and then using `self.state_machine.insert_input()`

Our build started failing due a `circular inclusion in "include" directive` which comes from the *second* inclusion of the `common.rst` above.  In this situation, I don't believe there is any circular inclusion -- we want the same content included twice; but it is not referencing itself.

I think it has something to do with `self.state.document.include_log` thinking that it has seen `common.rst` before.

I have isolated this down to the smallest example I can think of and attached that; it is also at https://paste.opendev.org/show/brTxHYllHebBIs1wHbfM/

When I run this I get

~~~
$ ./docutils-venv/bin/python3 ./recursive.py 
Write combined.rst
Write file1.rst
Write file2.rst
Write common.rst
file1.rst:1: (WARNING/2) circular inclusion in "include" directive:
file1.rst
> file1.rst
~~~



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.