Questions tagged [toctree]

Use this tag for questions about the toctree Sphinx directive. This directive is used to interconnect documentation files, other toctrees, and tables of contents.

.. toctree:: is a directive of the Python Sphinx document generation tool used to interconnect documentation files, other toctrees, and tables of contents.

This tag serves to distinguish questions specific to the specialized Sphinx .. toctree:: directive from other tables-of-contents (ToC) that may coexist, or be generated, in the same context. For example the reST ToC directive, or a LaTex ToC among others, in which case the generic should be used.

Additionally, this tag serves to filter questions that -altough textually containing the word "toctree"- are not about the directive in itself.

This tag can stand alone, but should be used in conjunction with the parent tag .

For official documentation on the .. toctree:: directive.

160 questions
126
votes
8 answers

Can sphinx link to documents that are not located in directories below the root document?

I am using Sphinx to document a non-Python project. I want to distribute ./doc folders in each submodule, containing submodule_name.rst files to document that module. I then want to suck those files into the master hierarchy to create a spec for…
mc_electron
  • 1,503
  • 3
  • 11
  • 13
86
votes
4 answers

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 …
NickChase
  • 1,442
  • 3
  • 15
  • 23
53
votes
4 answers

Sphinx autosummary "toctree contains reference to nonexisting document" warnings

I am trying to automatically create api docs for a large python codebase using Sphinx. I have tried using build_modules.py and sphinx-apidoc. With either one, I can get rst docs successfully created in my output directory for the packages and…
user1287170
  • 713
  • 1
  • 6
  • 8
49
votes
4 answers

How to include the toctree in the sidebar of each page

I'm generating html documentation in Sphinx. How do I modify the sidebar for each of the html pages in my document so that they include the toctree? By default the toctree only seems to display in the master_doc page, and only in the main area…
Travis Bear
  • 13,039
  • 7
  • 42
  • 51
40
votes
4 answers

How to expand all the subsections on the sidebar toctree in Sphinx?

I was wondering if there is a way to expand all the subsections under the headers that are included in the index.rst file? As an example, here is how it is: Section 1 Section 2 Section 3 And here is how I would like it to be: Section 1 Subsection…
Joe D
  • 401
  • 4
  • 3
33
votes
2 answers

How do I include the homepage in the Sphinx TOC?

Let’s say I’ve got a Sphinx project with the following sources: index.rst installation.rst templating/ index.rst module.rst fieldtype.rst index.rst (the homepage) has the following TOC tree: .. toctree:: :titlesonly: …
Brandon Kelly
  • 2,033
  • 2
  • 21
  • 38
33
votes
1 answer

Disabling individual Sphinx warning messages

I have many .rst files in my Sphinx tree which are intentionally excluded from any index tree. I get warnings like /filename.rst:: WARNING: document isn't included in any toctree How can I suppress specific warnings in Sphinx?
Mikko Ohtamaa
  • 82,057
  • 50
  • 264
  • 435
26
votes
1 answer

Unknown directive type "toctree". Error in Pycharm, but index.html works

When working in PyCharm, the preview mode of the document I am creating in Sphinx shows: System Message: ERROR/3 (, line 9) Unknown directive type "toctree". ..toctree:: :maxdepth: 2 file1 file2 I have included the autodoc extension in…
Wouter
  • 477
  • 2
  • 6
  • 8
26
votes
1 answer

Cannot Get TOCTREE in Sphinx to Show Link

I am new to Sphinx. I tried out the tutorial but I failed to generate the link in the contents. The error that I got C:\Users\mhaikalm\sphinxtest\source\index.rst:11: WARNING: toctree contains refe rence to document 'intro' that doesn't have a…
Haikal Nashuha
  • 2,958
  • 7
  • 44
  • 67
25
votes
3 answers

How to add Sphinx-generated index to the sidebar when using Read the Docs theme?

I'd like to have a link to the automatically generated index in the sidebar when using sphinx-rtd-theme. I've tried adding it to the toctree: .. toctree:: first second Index <:ref:`genindex`> but this resulted in WARNING: toctree…
VZ.
  • 21,740
  • 3
  • 39
  • 42
24
votes
4 answers

External Relative Link in Sphinx toctree directive

I'm using Sphinx to build my documentation. I'm using other tool for API reference. I have my docs in a directory and the API reference in directory name api inside of it. I want to have a link from the documentation to the API reference. I'm able…
Ido Ran
  • 10,584
  • 17
  • 80
  • 143
23
votes
2 answers

Use Sphinx autosummary recursively to generate API documentation

I want to use Sphinx's autosummary extension and templates to generate API docs recursively from docstrings. I want separate pages for each module, class, method, property and function. But it doesn't detect my templates at all. In fact, if I just…
Hameer Abbasi
  • 1,292
  • 1
  • 12
  • 34
22
votes
1 answer

Automatically create a toctree for autodoc classes in Sphinx

I'm looking to increase the documentation in one of my libraries. I've been using sphinx to help build the documentation and recently started exploring the autodoc extension. It seems like in most professional documentation, each class documentation…
Ben Hoff
  • 1,058
  • 1
  • 11
  • 24
21
votes
2 answers

How can i include the `genindex` in a Sphinx TOC?

Sphinx generates an index named genindex when building a documentation and therefore forbids to use that name for a document. Now, how would I include a link to that index in a table of contents? I've tried this: .. toctree:: :maxdepth: 2 …
funky-future
  • 3,716
  • 1
  • 30
  • 43
17
votes
2 answers

Prevent sub-section nesting in Python Sphinx when using toctree

I'm running into a problem in structuring my Sphinx users guide. I would like to form a chapter by having a main landing page (index.rst) that contains the chapter heading and an overview, and then separate sub-sections contained in different…
jeremiahbuddha
  • 9,701
  • 5
  • 28
  • 34
1
2 3
10 11