question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Files not included in TOC tree with .rst files are used as index / header

See original GitHub issue

Describe the bug Hi all, I am building a jupyter-book but some of my files are not included in the toc tree.

To Reproduce Steps to reproduce the behavior:

  1. Go to ‘https://github.com/lhoupert/from-python-to-numpy/tree/jb-version’, clone the directory and cd jb-version
  2. Build the jupyter-book jupyter-book build .

Expected behavior

My _toc.yml file is:

- file: 00-book

- header: Get started
- file: 01-preface
- file: 02-introduction
- file: 03-anatomy

- header: Vectorization
- file: 04-code-vectorization
- file: 05-problem-vectorization
- file: 06-custom-vectorization
- file: 07-beyond-numpy

- header: Conclusion
- file: 08-conclusion

- header: References
- file: 09-quick-reference
- file: 10-bibliography

but when the html is built a few sections are missing:

Screenshot 2020-07-15 at 11 36 47

You can see the whole website here

This is consistent with the warnings I got when building the website:


/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/00-book.rst:81: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/00-book.rst:91: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/00-book.rst:110: WARNING: Explicit markup ends without a blank line; unexpected unindent.

checking consistency... /Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/02-introduction.rst: WARNING: document isn't included in any toctree
/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/03-anatomy.rst: WARNING: document isn't included in any toctree
/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/05-problem-vectorization.rst: WARNING: document isn't included in any toctree
/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/06-custom-vectorization.rst: WARNING: document isn't included in any toctree
/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/07-beyond-numpy.rst: WARNING: document isn't included in any toctree
/Users/locupe/Dropbox/Work/Python/Repos_useful/from-python-to-numpy/jb-version/10-bibliography.rst: WARNING: document isn't included in any toctree

Interestingly, when I didnt put any header entries in the _toc.yml file, the html rendering only display the first two from my TOC.

You will also notice something strange happening on the first page of the website, the name of the files which were not included in the toc are listed: Screenshot 2020-07-15 at 11 42 13

Another problem with the warning errors below. They don’t make sense as my file 00-book.rst has only 74 lines…

from-python-to-numpy/jb-version/00-book.rst:81: WARNING: Explicit markup ends without a blank line; unexpected unindent.
from-python-to-numpy/jb-version/00-book.rst:91: WARNING: Explicit markup ends without a blank line; unexpected unindent.
from-python-to-numpy/jb-version/00-book.rst:110: WARNING: Explicit markup ends without a blank line; unexpected unindent.

Thank you for the help! Environment (please complete the following information):

  • Python Version [Python 3.7.4]
  • Output of Jupyter Book: 0.7.1

Additional context Add any other context about the problem here.

Issue Analytics

  • State:closed
  • Created 3 years ago
  • Comments:15 (7 by maintainers)

github_iconTop GitHub Comments

1reaction
lhoupertcommented, May 5, 2021

It seems that it is fixed now! thanks to https://github.com/executablebooks/jupyter-book/pull/1293 .

The only thing I add to do was to migrate my pre-existing toc to the new format (I just had to follow the instructions in my terminal after trying to build with the last version of master).

image

1reaction
lhoupertcommented, Jan 27, 2021

Thank you @AakashGfude for having a look. I updated a minimal example here: https://github.com/lhoupert/jupyter-book/tree/test-rst-toc/tests/books/toc/test_rst

The _toc.yml file is:

- file: content0

- part: Part1
  chapters:
  - file: content3
  - file: content3a

- part: Part2
  chapters:
  - file: content3b
  - file: content3c
  - file: content3d

When running jupyter-build in this directory. I don’t have the warning WARNING: Explicit markup ends without a blank line; unexpected unindent but I got these error messages:

checking consistency... /Users/locupe/Dropbox/Work/Python/Repos_fork/jupyter-book/tests/books/toc/test_rst/content3a.rst: WARNING: document isn't included in any toctree
/Users/locupe/Dropbox/Work/Python/Repos_fork/jupyter-book/tests/books/toc/test_rst/content3c.rst: WARNING: document isn't included in any toctree
/Users/locupe/Dropbox/Work/Python/Repos_fork/jupyter-book/tests/books/toc/test_rst/content3d.rst: WARNING: document isn't included in any toctree

Screenshot 2021-01-27 at 09 16 05

Read more comments on GitHub >

github_iconTop Results From Across the Web

Directives - Sphinx documentation
To create table of contents for current document (. rst file), use the standard reST contents directive. The representation of “TOC tree” is...
Read more >
WARNING: document isn't included in any toctree for included ...
AFAIK, every .rst file that is not explicitly included in a toctree is regarded as "stray" by Sphinx and a warning message is...
Read more >
Docs Markup and Syntax Guide - ODK Docs
The index.rst file serves as a front-page to the documentation and contains the main tables of content, defined using toctree directives.
Read more >
Toctree and the hierarchical structure of a manual
Only .rst files that are included in a toctree, are included in the menu. ... This will create a menu, using the header...
Read more >
Step 1: Getting started with RST - Sphinx Tutorial
A lot of these RST syntax examples are covered in the Sphinx reStructuredText Primer ... Go ahead and complete the toctree directive in...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found