Jupyter-book: Raise an error when a document contains multiple top level titles

[akhmerov]

Describe the bug

The rendered toc breaks when a document has multiple top level headers

To Reproduce

To reproduce create a book with a document which has two top level headers:

1. jupyter-book create test_book && cd test_book
2. echo "[{file: intro}, {part: part, chapters: [{file: content, title: title}]}]" > _toc.yml
3. printf "# title1\n\n# title2" > content.md
4. jupyter-book build .

Observe that the resulting toc looks like this:

So there are two toc entries, each referring to a different section within the source file. The title key from the toc is completely ignored.

This contradicts to the docs:

Chapters are the top-most book structure. The top level of your _toc.yml contains a list of chapters. The title of each file will be the chapter’s title.

Expected behavior

I'd expect one of the following to happen

• An error is raised due to a document containing multiple top level headers and only a single title toc key.
• A single chapter with a title "title" is created, and "title1" and "title2" are section titles within that document.

Environment

• Python Version: 3.8.3
• Package versions or output of jupyter-book --version:

Jupyter Book: 0.7.5
MyST-NB: 0.10.0
Sphinx Book Theme: 0.0.36
MyST-Parser: 0.12.7
Jupyter-Cache: 0.4.1

[choldgraf]

Hmm - well there is also this: https://jupyterbook.org/content-types/index.html#rules-for-all-content-types

which says you shouldn't have multiple top-level headers. We could make this raise a warning? Not sure how exactly to do it though...

[akhmerov]

That's reasonable, I assumed that it'd be the case. Would be also good to mention it around https://jupyterbook.org/customize/toc.html#how-headers-and-sections-map-onto-to-book-structure as well. Nevertheless the breaking is subtle and not obvious at a glance. Therefore I suggest to raise an error.

[mmcky]

@choldgraf I think a warning here would be good. You have done a nice job in the current docs but some users won't read through it :-) and might prevent bug reports.

thanks for these test cases @akhmerov. I am currently doing some homework to understand how various toc structures are working (in addition to some common patterns I think users will try) in an effort to improve the relationship between _toc.yml and some more complex book elements such as frontmatter etc. Playing with some upstream ideas for support of special toctree elements in sphinx in this thread for appendix and frontmatter to help control style in html and latex based on more contextual info.

[akhmerov]

@mmcky frontmatter / appendix sound great.

Note for catching of the error: due to sphinx peculiarities, multiple h2 in a document that lacks h1 will lead to the same result.

[choldgraf]

note - I am all for warnings, I'm just not sure how to do it! PRs are welcome :-)