WARNING: document isn't included in any toctree for included file
Solution 1
Sphinx will complain about this whether the file is included or not.
However, you can specifically exclude files by using the exclude_patterns config value.
So for your case you might try to change Sphinx's conf.py
file with something like:
exclude_patterns = ['pages/reference-architecture', 'some/other/file.txt']
You can exclude individual files, directories, or use file globbing patterns to match groups of files this way.
EDIT: See: Joakim's answer for another option that was added after this answer was created.
Solution 2
If you only want to ..include::
a document in another document, without having it appear in any toctree
.
Add :orphan:
to the top of your document to get rid of the warning.
This is a File-wide metadata option. Read more from the Sphinx documentation.
Solution 3
I had a situation where I couldn't edit the documents I wanted to be brought in as a git submodule. The documents already had their own structure including TOC page written in Markdown and I did want them to be processed by sphinx for consistency of formatting.
What I found I could do is specify a hidden toctree to make toctree aware of the documents, but not clutter up the toctree or add a bunch of errors to my sphinx build output.
* :doc:`Additional Book <external/index>`
.. toctree::
:hidden:
external/documentA.md
external/documentB.md
Solution 4
Indentation worked:
toctree::
:maxdepth: 2
hello <h.rst>
abc <your.rst>
NickChase
Updated on October 20, 2021Comments
-
NickChase over 2 years
I'm getting the warning:
WARNING: document isn't included in any toctree
for files that exist in the document because they've been explicitly included. So I have the index file:
.. toctree:: :maxdepth: 2 pages/0010-foo pages/0020-bar
In the file 0020-bar.rst, I'm specifically including a number of other files, as in:
.. contents:: :local: .. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst
But when I build the project, I still get a warning that 0070-baz.rst isn't in any toctree, as in:
/home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn't included in any toctree
The weird thing is that I can see the content in the output. Is this normal? Does this warning always appear for files that are explicitly included rather than included via toctree?
-
pzkpfw over 8 yearsThe indentation you're showing is by no means required, however, an empty row between
:maxdepth: 2
and the next row is. It also could/should be simplyh
(filename minus rst), unless there is a specific reason you want to override the title of document. -
Josiah over 4 yearsAlso, see
:hidden:
option fortoctree
. -
Daniel Arndt almost 4 yearsThanks, this seems like a good answer in a few cases. Our use case was using a generated file that we didn't want to manually inject the
:orphan:
tag at the top. -
panc about 3 yearsI like this answer as it also help me to track which external docs are referenced in the current doc.