phpDocumentor / phpDocumentor/guides
[Bug]: Warning is issued when a document is added to multiple parents
Nobody has claimed this yet.
- 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:
- index
- design
- implementation
- test
- release
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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