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

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.

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.

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

Indentation worked:

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