phpDocumentor / phpDocumentor/guides

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

Open
#1,277 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug triage
Dominant language
PHP
Stars
36
Forks
22
Avg merge
2d 2h
Merged PRs (30d)
24

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the warning with the shown index.rst, implementation.rst, design.rst, release.rst, and test.rst toctree structure, then trace where Guides reports multiple parents during the documentation build. Compare the resulting order and warnings with the expected Sphinx behavior; done means the valid shared document no longer produces this warning and the expected toctree order is preserved.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.