document not in toctree warning when including files only for parallel builds

[vermeeren]

Problem

A warning is emitted when including files that themselves are not in the toctree, but ONLY for parallel builds (e.g. -j auto). @tk0miya comment in #3167 is correct, without -j it does work properly.

Procedure to reproduce the problem

In some main index.rst, which is included in toctree.

Some section
------------

Foobar, see below table for details.

.. include:: table.rst

This table.rst, not included by any toctree, is defined as:

.. list-table::

        * * arbitrary list table
          * arbitrary list table

Error logs / results

WARNING: document isn't included in any toctree

Expected results

No warning, as with without -j.

Reproducible project / your project

I can provide sources and a link to example code if required. It is from a project currently developed in private to avoid attention during initial phase, but will be AGPLv3 later. So unless necessary I rather keep this private for now.

Environment info

• OS: GNU/Linux
• Python version: 3.6.6
• Sphinx version: 1.7.5

Workaround

We currently put :orphan: at the top of to-be included RST and then use :start-line: 2 for include directive.

[vermeeren]

Also a small question: is it possible for Sphinx to not render these non-toctree include RST files? They currently generate a HTML page and show up in the generated doc search.

Is changing the file extension of the to-be included files the recommended solution for this?

Edit: with this I mean that the file extension is not listed in conf.py source_suffix option.

Edit 2: we changed extension of to-be included file to .irst, this worked properly.

[tk0miya]

Thank you for reporting.
I just made a PR #5200. Could you try this please?
Thanks,

[vermeeren]

Hi, the PR fixed some of the warnings. Thanks for the quick reply!

On a single index.rst of a page I have 5 .. include:: in several sections. Before this patch all 5 of them would give a warning, now only 2 of them give a warning. Possibly some other edge case is going wrong?

[tk0miya]

Hmm... I can't imagine about the warning. To fix it, I need reproducible example.

[vermeeren]

I created test example in public doc template, please see: https://git.mel.vin/template/doc/tree/sphinx-issue-5198/doc/sphinx-issue-5198

The associated build log: https://git.mel.vin/template/doc/-/jobs/10021

Note that this template uses CMake to configure, it is based upon C/C++ template. You also need sphinxcontrib-plantuml to build, perhaps copying the sphinx-issue-5198 folder to other project is easier if you do not have the required deps.

mkdir build
cd build
cmake -DDOC:STRING=html ..
make doc

Output on my machine, without WERROR on:

$ make doc
Scanning dependencies of target doc
Generating sphinx html documentation
/home/melvin/dev/template/doc/doc/sphinx-issue-5198/a.rst: WARNING: document isn't included in any toctree
/home/melvin/dev/template/doc/doc/sphinx-issue-5198/b.rst: WARNING: document isn't included in any toctree
/home/melvin/dev/template/doc/doc/sphinx-issue-5198/c.rst: WARNING: document isn't included in any toctree
/home/melvin/dev/template/doc/doc/sphinx-issue-5198/d.rst: WARNING: document isn't included in any toctree
/home/melvin/dev/template/doc/doc/sphinx-issue-5198/e.rst: WARNING: document isn't included in any toctree
Output at /home/melvin/dev/template/doc/build/doc/html
Built target doc

When editing /doc/CMakeLists.txt and changing -j auto to -j 1 it works without warning. Note that my desktop has 8 threads. My desktop has the patch from PR #5200 included, the CI does not.

I think this may happen when the included files begin to render before the main index.rst is finished with rendering, so the environment merges in some odd order?

[tk0miya]

Thank you for example! I made another PR #5313 for this. And I confirmed it surely fixes the warning.

[tk0miya]

Now #5313 is merged. Please let me know if it does not work well.
Thanks,

[vermeeren]

Thank you for the fix, I confirmed it works with all projects that had the issue and it does.

Edit: compared to the initial PR the second one doesn't update changelog, perhaps forgotten or maybe intentional?