CODEWITHSUNDEEP
python-sphinxrestructuredtexttoctree
NickChase
NickChase

Reputation: 1512

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

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?

Upvotes: 93

Views: 71138

Answers (5)

Shamsul Arefin
Shamsul Arefin

Reputation: 1917

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

Upvotes: 0

Kevin Horn
Kevin Horn

Reputation: 4295

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.

Upvotes: 49

Josiah
Josiah

Reputation: 2866

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

Upvotes: 7

Joakim
Joakim

Reputation: 11998

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.

Upvotes: 83

diveinsky
diveinsky

Reputation: 165

Indentation worked:

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

Upvotes: 3

Related Questions