Sphinx: Consistency check is not considering included documents

[felipecaputo]

Subject: I'm currently making documentation in more the one file to keep sanity, and including files into the main document files.

Problem

• When I make the project, the consistency checks says that FileA.rst ins't included in any toctree, but it is by the include

Procedure to reproduce the problem

Create a .rst file and include another .rst file

Then build the project

O que é uma mensagem
----------------------

No barramento, mensagens são as informações trocadas entre as operações. Essas
mensagens representam os contratos entre os processadores e precisam ser definidas preferencialmente
em formato **JSON**. Este contrato precisa então transformado em uma *Interface* e uma *Classe* no Delphi.

A *Interface* é necessário devido a implementação do SDK que considera toda mensagem que chega uma
**IIntegrationMessage**, desta forma evitando a necessidade de manter heranças e permitindo a alteração
das versões das mensagens apenas com a adição de uma nova interface que contenha os novos campos adicionados
ao contrato por exemplo.

.. include:: how_to.rst

Error logs / results

(env) PS C:\src\git-softplan\unj-integracoes\delphiSdk\docs> .\make html
Running Sphinx v1.6.4
loading translations [pt_BR]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] mensagens/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... C:\src\git-softplan\unj-integracoes\delphiSdk\docs\mensagens\how_to.rst: WARNING:
 document isn't included in any toctree
done
preparing documents... done

Expected results

Consider included rst files as used and included if the file it was included into was in a toctree

Reproducible project / your project

Environment info

• OS: Windows 10
• Python version: 3.6.3
• Sphinx version: 1.6.4
  docs.zip

[stephenfin]

Yeah, this is a long-standing issue and I'd imagine there are existing issues open for this. In the interim, you can stick an :orphan: tag in the file and include that (noting #1545) or simply use a different file extension (.inc?)

[felipecaputo]

Thanks @stephenfin, I did the search for an open issue and didn't found it. I will solve it with :orphan:. o/

[tk0miya]

Wait, sphinx marks included files as a part of document (see #2603). So I think the warning is strange for me. I will take a look this now.

[tk0miya]

I can't reproduce the warning with your attached project.

$ docker run -it --rm tk0miya/sphinx-html bash
# apt install curl unzip
# curl -LO https://github.com/sphinx-doc/sphinx/files/1369697/docs.zip
# unzip docs.zip
# cd docs
# pip3 install sphinx_materialdesign_theme
# make html SPHINXBUILD='python3 -msphinx'
Running Sphinx v1.6.4
loading translations [pt_BR]... done
loading pickled environment... not yet created
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/2/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: 3 added, 0 changed, 0 removed
reading sources... [100%] mensagens/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] mensagens/index
generating indices... genindex
writing additional pages... search
copying static files... WARNING: html_static_path entry '/docs/docs/_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.

Build finished. The HTML pages are in _build/html.

Am I something wrong?

[tk0miya]

Now I'm closing this again, because it seems not a bug of Sphinx.
Thanks,