Noise "document is referenced from multiple doctrees" when building docs

[marc-hb]

Describe the bug

As of today's commit bfea9cf, there are 50 instances of the message "document is referenced from multiple doctrees... " when building the documentation incrementally. This drowns any new warning which gets missed and added to the giant, existing and ever-growing pile of warnings already reported at #82403

"Document is referenced from multiple doctrees" is the most annoying subset of #82403 because it affects not just the build from scratch which can easily be ignored (just build two or three times), but also the incremental build loop: edit, make, edit, make,...

It looks like a regression because the incremental build used to be "clean" but maybe this just came in newer versions of sphinx-build?

PS: It's that time of year where trying to fix one doc typo (unrelated #95442) takes many hours due to totally unrelated build issues :-(

Regression

• This is a regression... maybe?

Steps to reproduce

cd doc
# build from scratch, huge wall of warnings (#82403)
make
# incremental builds, medium wall of warnings (this issue). Only 50 lines.
make
# For the documentation, incremental builds seem to start only after the 3rd time!?
make

Relevant log output

checking consistency... zephyr/doc/_build/src/boards/arm/fvp_baser_aemv8r/doc/debug-with-arm-ds.rst: document is referenced in multiple toctrees: ['boards/arm/fvp_baser_aemv8r/doc/aarch64', 'boards/arm/index'], selecting: boards/arm/index <- boards/arm/fvp_baser_aemv8r/doc/debug-with-arm-ds
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_an521.rst: document is referenced in multiple toctrees: ['boards/arm/index', 'boards/arm/mps2/doc/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_an521
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_armv6m.rst: document is referenced in multiple toctrees: ['boards/arm/index', 'boards/arm/mps2/doc/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_armv6m
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_armv7m.rst: document is referenced in multiple toctrees: ['boards/arm/index', 'boards/arm/mps2/doc/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_armv7m
zephyr/doc/_build/src/build/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- build/index
zephyr/doc/_build/src/connectivity/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- connectivity/index
zephyr/doc/_build/src/connectivity/networking/api/ptp.rst: document is referenced in multiple toctrees: ['connectivity/networking/api/tsn', 'connectivity/networking/api/protocols'], selecting: connectivity/networking/api/tsn <- connectivity/networking/api/ptp
zephyr/doc/_build/src/contribute/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- contribute/index
zephyr/doc/_build/src/develop/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- develop/index
zephyr/doc/_build/src/hardware/cache/guide.rst: document is referenced in multiple toctrees: ['hardware/cache/index', 'hardware/index'], selecting: hardware/index <- hardware/cache/guide
zephyr/doc/_build/src/hardware/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- hardware/index
zephyr/doc/_build/src/introduction/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- introduction/index
zephyr/doc/_build/src/kernel/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- kernel/index
zephyr/doc/_build/src/project/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- project/index
zephyr/doc/_build/src/safety/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- safety/index
zephyr/doc/_build/src/samples/boards/st/bluetooth/interactive_gui/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/bluetooth/index', 'samples/boards/st/index'], selecting: samples/boards/st/index <- samples/boards/st/bluetooth/interactive_gui/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/adc/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/adc/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/blinky/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/blinky/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/serial_wakeup/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/serial_wakeup/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/standby_shutdown/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/standby_shutdown/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/stm32wb_ble/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/stm32wb_ble/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/stop3/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/stop3/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/suspend_to_ram/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/suspend_to_ram/README
zephyr/doc/_build/src/samples/boards/st/power_mgmt/wkup_pins/README.rst: document is referenced in multiple toctrees: ['samples/boards/st/index', 'samples/boards/st/power_mgmt/index'], selecting: samples/boards/st/power_mgmt/index <- samples/boards/st/power_mgmt/wkup_pins/README
zephyr/doc/_build/src/samples/shields/lmp90100_evb/rtd/README.rst: document is referenced in multiple toctrees: ['samples/shields/lmp90100_evb/lmp90100_evb', 'samples/shields/shields'], selecting: samples/shields/shields <- samples/shields/lmp90100_evb/rtd/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks01a2/sensorhub/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks01a2/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks01a2/README <- samples/shields/x_nucleo_iks01a2/sensorhub/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks01a2/standard/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks01a2/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks01a2/README <- samples/shields/x_nucleo_iks01a2/standard/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks01a3/sensorhub/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks01a3/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks01a3/README <- samples/shields/x_nucleo_iks01a3/sensorhub/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks01a3/standard/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks01a3/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks01a3/README <- samples/shields/x_nucleo_iks01a3/standard/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks02a1/microphone/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks02a1/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks02a1/README <- samples/shields/x_nucleo_iks02a1/microphone/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks02a1/sensorhub/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks02a1/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks02a1/README <- samples/shields/x_nucleo_iks02a1/sensorhub/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks02a1/standard/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks02a1/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks02a1/README <- samples/shields/x_nucleo_iks02a1/standard/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks4a1/sensorhub1/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks4a1/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks4a1/README <- samples/shields/x_nucleo_iks4a1/sensorhub1/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks4a1/sensorhub2/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks4a1/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks4a1/README <- samples/shields/x_nucleo_iks4a1/sensorhub2/README
zephyr/doc/_build/src/samples/shields/x_nucleo_iks4a1/standard/README.rst: document is referenced in multiple toctrees: ['samples/shields/x_nucleo_iks4a1/README', 'samples/shields/shields'], selecting: samples/shields/x_nucleo_iks4a1/README <- samples/shields/x_nucleo_iks4a1/standard/README
zephyr/doc/_build/src/samples/subsys/canbus/isotp/README.rst: document is referenced in multiple toctrees: ['samples/subsys/canbus/canbus', 'samples/subsys/canbus/canbus'], selecting: samples/subsys/canbus/canbus <- samples/subsys/canbus/isotp/README
zephyr/doc/_build/src/security/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- security/index
zephyr/doc/_build/src/services/index.rst: document is referenced in multiple toctrees: ['index', 'index-tex'], selecting: index-tex <- services/index
zephyr/doc/_build/src/snippets/espressif/flash-16M/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/flash-16M/README
zephyr/doc/_build/src/snippets/espressif/flash-32M/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/flash-32M/README
zephyr/doc/_build/src/snippets/espressif/flash-4M/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/flash-4M/README
zephyr/doc/_build/src/snippets/espressif/flash-8M/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/flash-8M/README
zephyr/doc/_build/src/snippets/espressif/psram-2M/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/psram-2M/README
zephyr/doc/_build/src/snippets/espressif/psram-4M/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/psram-4M/README
zephyr/doc/_build/src/snippets/espressif/psram-8M/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/psram-8M/README
zephyr/doc/_build/src/snippets/espressif/psram-reloc/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/psram-reloc/README
zephyr/doc/_build/src/snippets/espressif/psram-wifi/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/psram-wifi/README

Impact

Annoyance – Minor irritation; no significant impact on usability or functionality.

Environment

Linux
sphinx-build --version 8.2.3
Zephyr bfea9cf

Additional Context

• doc: snippets: group some snippets together #95433
• doc: samples: fix doc build warnings #95436
• doc: conf.py: fix warnings about docs appearing in index and index-tex #95483
• boards: doc: arm: fix documentation structure for mps2 and fvp_baser_aemv8r #95532

[marc-hb]

I found that the warning logging comes from _check_toc_parents sphinx/environment/__init__.py, see below.

I tried a naive suppress_warnings = ['toc.multiple_toc_parents'] in doc/conf.py but that did not work because... this is not a warning, just a logger.info(). Looking at sphinx/util/logging.py, suppress_warning really is only about warnings.

sphinx/environment/__init__.py

def _check_toc_parents(toctree_includes: dict[str, list[str]]) -> None:


        if len(parents) > 1:
            logger.info(
                __(
                    'document is referenced in multiple toctrees: %s, selecting: %s <- %s'
                ),
                ...
                type='toc',
                subtype='multiple_toc_parents',
            )

[marc-hb]

Crazy thought: maybe a lot of problems reported could be... fixed?

For instance, snippets/espressif/index.rxt includes **/*. But snippets/index.rxt already does that?!

snippets/espressif/psram-reloc/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/psram-reloc/README
snippets/espressif/psram-wifi/README.rst: document is referenced in multiple toctrees: ['snippets/espressif/index', 'snippets/index'], selecting: snippets/index <- snippets/espressif/psram-wifi/README

EDIT: #95433, #95436, #95483,...

[marc-hb]

Workaround, sort of: cd doc; SPHINXOPTS_EXTRA=-q time make

This makes the build too quiet, losing all sense of progress and losing relevant INFO logs for work in progress, but it helps focus the output on relevant warnings.

cc: @kartben , @gmarull

[marc-hb]

This is an attempt to capture and move here the interesting discussion happening in PR #95436 and explanation from @kartben

it's not necessarily a bug as one might very well want things to be "mounted" in different toctrees but the INFO makes sense so that the user knows that's the case because they might not otherwise realize that the "breadcrumb" for their pages contained in multiple hierarchies will just show a random/undeterministic trail

I think we should be able to get rid of most of these notices except for the ones taking about index.rst vs. index-tex.rst as they are pretty much a Sphinx bug IIRC

...

I should have said that while one might want a doc to appear in multiple toctrees, I think that's something we should actually disallow (hence effectively make this a WARNING I guess), due to the aforementioned "breadcrumb-will-be-whatever" issue.

[marc-hb]

except for the ones taking about index.rst vs. index-tex.rst as they are pretty much a Sphinx bug IIRC

This would get the total number down to 11 right now, that would be a major progress as it would not really drown other, relevant warnings any more! Thanks.

while one might want a doc to appear in multiple toctrees, I think that's something we should actually disallow (hence effectively make this a WARNING I guess),

Short of making changes in Sphinx itself, I don't see how you could promote this to a WARNING.

You could try to scan the output but that would quite hackish - and this would need to ignore the index-tex.rst lines, making it even more hackish.

EDIT: silenced by #95483

[marc-hb]

After rebasing to 8f85d8e and cherry-picking #95483, I'm down to just 15 lines. @kartben is on a roll!

checking consistency... zephyr/doc/_build/src/boards/arm/fvp_baser_aemv8r/doc/debug-with-arm-ds.rst: document is referenced in multiple toctrees: ['boards/arm/index', 'boards/arm/fvp_baser_aemv8r/doc/aarch64'], selecting: boards/arm/index <- boards/arm/fvp_baser_aemv8r/doc/debug-with-arm-ds
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_an521.rst: document is referenced in multiple toctrees: ['boards/arm/mps2/doc/index', 'boards/arm/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_an521
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_armv6m.rst: document is referenced in multiple toctrees: ['boards/arm/mps2/doc/index', 'boards/arm/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_armv6m
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_armv7m.rst: document is referenced in multiple toctrees: ['boards/arm/mps2/doc/index', 'boards/arm/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_armv7m
zephyr/doc/_build/src/connectivity/networking/api/ptp.rst: document is referenced in multiple toctrees: ['connectivity/networking/api/protocols', 'connectivity/networking/api/tsn'], selecting: connectivity/networking/api/tsn <- connectivity/networking/api/ptp
zephyr/doc/_build/src/hardware/cache/guide.rst: document is referenced in multiple toctrees: ['hardware/cache/index', 'hardware/index'], selecting: hardware/index <- hardware/cache/guide
zephyr/doc/_build/src/snippets/espressif/flash-16M/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/flash-16M/README
zephyr/doc/_build/src/snippets/espressif/flash-32M/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/flash-32M/README
zephyr/doc/_build/src/snippets/espressif/flash-4M/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/flash-4M/README
zephyr/doc/_build/src/snippets/espressif/flash-8M/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/flash-8M/README
zephyr/doc/_build/src/snippets/espressif/psram-2M/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/psram-2M/README
zephyr/doc/_build/src/snippets/espressif/psram-4M/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/psram-4M/README
zephyr/doc/_build/src/snippets/espressif/psram-8M/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/psram-8M/README
zephyr/doc/_build/src/snippets/espressif/psram-reloc/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/psram-reloc/README
zephyr/doc/_build/src/snippets/espressif/psram-wifi/README.rst: document is referenced in multiple toctrees: ['snippets/index', 'snippets/espressif/index'], selecting: snippets/index <- snippets/espressif/psram-wifi/README

[kartben]

zephyr/doc/_build/src/boards/arm/fvp_baser_aemv8r/doc/debug-with-arm-ds.rst: document is referenced in multiple toctrees: ['boards/arm/index', 'boards/arm/fvp_baser_aemv8r/doc/aarch64'], selecting: boards/arm/index <- boards/arm/fvp_baser_aemv8r/doc/debug-with-arm-ds
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_an521.rst: document is referenced in multiple toctrees: ['boards/arm/mps2/doc/index', 'boards/arm/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_an521
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_armv6m.rst: document is referenced in multiple toctrees: ['boards/arm/mps2/doc/index', 'boards/arm/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_armv6m
zephyr/doc/_build/src/boards/arm/mps2/doc/mps2_armv7m.rst: document is referenced in multiple toctrees: ['boards/arm/mps2/doc/index', 'boards/arm/index'], selecting: boards/arm/mps2/doc/index <- boards/arm/mps2/doc/mps2_armv7m

those are addressed with #95532

[marc-hb]

Only two left after #95532 and others listed above.

zephyr/doc/_build/src/connectivity/networking/api/ptp.rst: document is referenced in multiple toctrees: ['connectivity/networking/api/protocols', 'connectivity/networking/api/tsn'], selecting: connectivity/networking/api/tsn <- connectivity/networking/api/ptp
zephyr/doc/_build/src/hardware/cache/guide.rst: document is referenced in multiple toctrees: ['hardware/index', 'hardware/cache/index'], selecting: hardware/index <- hardware/cache/guide

[marc-hb]

while one might want a doc to appear in multiple toctrees, I think that's something we should actually disallow (hence effectively make this a WARNING I guess),

Short of making changes in Sphinx itself, I don't see how you could promote this to a WARNING.

To stop these from creeping back, maybe a CI workaround like this? UNTESTED

--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -136,8 +136,9 @@ jobs:
 
         DOC_TAG=${DOC_TAG} \
         SPHINXOPTS="-j ${JOB_COUNT} -W --keep-going -T" \
-        SPHINXOPTS_EXTRA="-q -t publish" \
-        make -C doc ${DOC_TARGET}
+        SPHINXOPTS_EXTRA="-t publish" \
+        (set -o pipefail; make -C doc ${DOC_TARGET} | tee doc_build.log )
+        if grep -i 'document.*referenced.*multiple.*toctrees' doc_build.log; then exit 1; fi
 
         # API documentation coverage
         python3 -m coverxygen --xml-dir  doc/_build/html/doxygen/xml/ --src-dir include/ --output doc-coverage.info