WARNING: document isn't included in any toctree for included file

Question

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?

Torques

AFAIK, every .rst file that is not explicitly included in a toctree is regarded as "stray" by Sphinx and a warning message is emitted. See also this answer: https://mcmap.net/q/242528/-disabling-individual-sphinx-warning-messages. – Cocksure

Answer 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.

Apc

Answer 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.

Heerlen

Also, see :hidden: option for toctree. – Isopropyl

Answer 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

Isopropyl

Thanks, 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. – Rayfordrayle

I like this answer as it also help me to track which external docs are referenced in the current doc. – Rummer

Answer 4

Indentation worked:

  toctree::   
   :maxdepth: 2
       hello <h.rst>
       abc <your.rst>

Embank

The 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 simply h (filename minus rst), unless there is a specific reason you want to override the title of document. – Seidule

Answer 5

in my case i was including a readme.MD file, but it by default accepts only .md file with myst extension. when i changed the file format, it did not say anymore

Interstate