[Bug]: Warning is issued when a document is added to multiple parents

[wouterj]

Summary

Guides does not support adding a document to 2 different parents in the toctree. This is supported by Sphinx.

Although probably not relevant, the warnings that are issued create a lot of noise when building the Symfony docs: https://github.com/wouterj/symfony-docs-guides/actions/runs/19391242509/job/55484996045

Code snippet that reproduces the problem

Create a small doc with a toctree like this:

index.rst
├─ design.rst
├─ implementation.rst
│  ├─ design.rst
│  └─ test.rst
└─ release.rst

Rst files

.. index.rst

Homepage
========

.. toctree::

    design
    implementation
    release

.. implementation.rst

Implementation
==============

.. toctree::

    design
    test

design.rst, release.rst and test.rst are empty

The design.rst now has both Index and Implementation as parents.
This triggers a warning with Guides:

app.WARNING: Document design has been added to parents index and implementation. The `toctree`
directive changes the position of documents in the document tree. Use the `menu` directive to
only display a menu without changing the document tree.

Expected output

Sphinx accepts the doc structure, and generates a toctree order like this:

1. index
2. design
3. implementation
4. test
5. release

[wouterj]

Our tests contain a wonderful document describing the Sphinx behavior: https://github.com/symfony-tools/docs-builder/blob/main/tests/fixtures/source/json/design.rst

Basically, instead of first reading the whole index.rst toctree, before reading the design.rst toctree, Sphinx will read each item as they come. So:

1. index.rst is read, design.rst is found in the toctree. It'll be marked as next document.
2. design.rst is read, no toctree found
3. next item in the index.rst toctree is discovered: implementation.rst, it'll be marked as next for design.rst
4. implementation.rst is read, new toctree found. design.rst is already discovered, so it is skipped, test.rst is new. It is marked as next
5. test.rst is read, no toctree found
6. no new items in the toctree of implementation.rst is found
7. next item from index.rst is discovered: release.rst. It is marked as next for test.rst
8. release.rst is read, no toctree found
9. no more items in index.rst found, parsing is finished.This creates the toctree order described under Expected output.

---

This gets even more important when the toctree of index.rst listed design after implementation:

.. toctree::

    implementation
    design
    release

Now, design.rst is discovered by implementation.rst. As a result, the next item for design will not be release (from index.rst's toctree), but test (from implementation.rst's toctree).

1. index
2. implementation
3. design
4. test
5. release

[linawolf]

The sphinx behaviour is not documented as far as we could tell, so we interpreted it as "undefined behaviour" and as it was creating yet another layer to an already very complicated topic we decided to issue a warning and clean up the docs where this is used.

Where a reference to another page is beeing used we use just that - a reference in the toc. Where we want to display a menu we use the menu directive as suggested by the warning. This way we can have a clear differnciation on when the toctree should or shouldnt be changed that was not possible with sphinx. It did require some changes in our documentation.

[linawolf]

Regarding the large log #920 might be a missing feature