Use `- chapter:` top-level sections in the `_toc.yml` file

Jupyter Book currently lets you split sub-sections of files with headers above each using the following structure:

- header: my header
- file: myfile
- file: second file
- header: my second header
- file: third file
- file: fourth file

This will then make the assumption that these should be split into two groups of files w/ two headers.

One option

Under the hood, Sphinx treats these groups of files as chapters. So, I wonder if we should just be explicit about this in _toc.yml, and instead accomplish the above with:

- chapter: My header
  sections:
  - file: myfile
  - file: second file
- chapter: My second header
  sections:
  - file: third file
  - file: fourth file

This is slightly more verbose and in some ways maybe less-flexible. But, it’s also more explicit, makes fewer assumptions, and I think is easier to understand. It also opens the path for any toctree-based functionality in Sphinx, like so:

- chapter: My header
  numbered: true
  sections:
  - file: myfile
  - file: second file

or even wacky stuff like

- chapter: My header
  glob: true
  sections:
  - file: folder/*

Another option

Another approach we could take is to simply generalize our current structure so that people can explicitly provide groups of files. Like so:

- section: My header
  files:
  - myfile
  - second file
- section: My second header
  files:
  - file: third file
  - file: fourth file

and then this could be arbitrarily nested, like so:

- section: My header
  files:
  - file: myfile
  - file: second file
    sections:
      - section:
        - file: third file
        - file: fourth file

What do folks think? I imagine that this would make @jstac and @mmcky happier? What about @chrisjsewell? Would also be curious whether @bmcfee would consider this an improvement

[choldgraf]

wohoo!

ok I’m gonna close this one once again as I think it’s resolved in a way that is consistent with our (and Sphinx’s) mental model of things

[choldgraf]

I’d like some quick feedback on whether we can merge https://github.com/executablebooks/jupyter-book/pull/834. It is a minimal change to (I think) correct the mismatch that I describe above (basically, it just renames - chapters: to instead be - parts:).

I think we should do it sooner than later, and make a patch release, because right now we’re encouraging users to follow a pattern that isn’t semantically correct, and will be deprecated soon.

We can keep iterating in an issue about other ways we want to extend toc.yml, but I think #834 is the crucial one right now

That PR enables the following TOC structure:

- file: intro
- part:
  chapters:
  - file: chapter1
  - file: chapter2
- part: A named part
  chapters:
  - file: chapter1
  - file: chapter2