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

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

> Additionally, this only seems to occur with docutils 0.17 -- if I downgrade to 0.16 or upgrade to 0.18 I don't the same build error! 

This is very important information, because  [bugs:#366] was reported for 0.17 and fixed in 0.18.

The bug report described cases of "false positives" in the circular inclusion detection, reproducible in stock Docutils for specific input cases. Maybe your problem is triggered by the same fault to the 0.17 version of the detection algorithm.
The fix includes incompatible changes to the "manual management" of the `include_log` required around an `insert_input` call. This means any fix on your side should be tested across Docutils versions :(


---

** [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:** Wed Nov 02, 2022 07:14 AM 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.