#424 Wrong circular inclusion detection

[Yangsu Kim]

Following warning is displayed with inclusion failure when parsing body.rst

body.rst:34: Warning: circular inclusion in "include" directive: gap.rst < gap.rst < body.rst

It is tesed on 0.17.1. I suspect wrong self.lineno from the 4th include due to short distance from the 3rd include.

body.rst

.. _my_table:
.. table:: a
   :class: longtable
   :widths: 100

   +----------------------+
   | a                    |
   +======================+
   | a                    |
   |                      |
   | .. include:: gap.rst |
   |                      |
   | a                    |
   +----------------------+
   | a                    |
   |                      |
   | .. include:: gap.rst |
   |                      |
   | a                    |
   +----------------------+
   | a                    |
   |                      |
   | .. include:: gap.rst |
   |                      |
   | a                    |
   |                      |
   | .. include:: gap.rst |
   |                      |
   | a                    |
   +----------------------+
   | a                    |
   |                      |
   | .. include:: gap.rst |
   |                      |
   | a                    |
   +----------------------+

gap.rst

.. raw:: latex

   \vspace{2mm}

[Günter Milde]

On 2021-09-10, Yangsu Kim via Docutils-develop wrote:

Following warning is displayed with inclusion failure when parsing body.rst

body.rst:34: Warning: circular inclusion in "include" directive: gap.rst < gap.rst < body.rst

Thank you for reporting.
Until this is sorted out (and maybe even afterwards),
I recommend using a substitution_ instead of an include:

body.rst

.. |gap| raw:: latex

     \vspace{2mm}

.. table:: a
   :name: my_table
   :class: longtable

   +----------------------+
   | a                    |
   |                      |
   | |gap|                |
   |                      |
   | a                    |
   +----------------------+

[Yangsu Kim]

Thank you for your advise. The substitution method works correctly and better!

[Günter Milde]

It seems the detection mechanism in directives.misc.Include is unreliable for table content because it relies on the line number (self.lineno). This is easy to understand for the minimal failing example with cells in a row:

==================== ====================
.. include:: gap.rst .. include:: gap.rst
==================== ====================

but also the case for cells in a column:

+----------------------+
| .. include:: gap.rst |
+----------------------+
| .. include:: gap.rst |
+----------------------+

and is independent of the content of the included file ( as long as it is valid at the place of inclusion).

(maybe self.lineno is local to a table cell in tables??)

[Günter Milde]

On 2021-10-03, Mickey Endito via Docutils-develop wrote:

I noticed that docutils reported a false cyclic inclusion, when combining
directives using nested_parse() and includes.

MWE consists of three files: mwe.rst, incl1.rst, incl2.rst:
mwe.rst::

 .. note::

    .. include:: incl1.rst
    .. include:: incl1.rst

incl1.rst::

 .. note::
    .. include:: incl2.rst

incl2.rst::

 Some text but can also be an empty file.

The command rst2html.py >/dev/null produces::

mwe.rst:8: (WARNING/2) circular inclusion in "include" directive: incl1.rst < incl2.rst < incl1.rst < mwe.rst

So far it seems as all three files and both .. note:: and both .. include::
directives are necessary to trigger this.

I had a quick look, it seems like on the second nested_parse() (the note of
incl1.rst) the included part is not inserted into the outer (parse of mwe.rst)
ViewList. Thus, the (internal) line numbers of the outer list are
"off"/"outdated" and the cycle detection (which uses the "new" numbers) in
run() of the class Include in docutils/parsers/rst/directives/misc.py is
triggered.
...

The common feature is, that nested parsing can fool the current circular inclusion heuristics.

[Günter Milde]

Fixed in r8851. Thanks for reporting.

[Günter Milde]

Fixed in Docutils 0.18.