Subsections without extra (empty) file?

[michaelaye]

Hi!
First let me thank the providers of these awesome tools. I love to see and share my pretty documentation!

I am developing my packages with nbdev and would like to generate the documentation via the existing notebooks.

Issue:
Subpackages in nbdev are indicated via a special comment in the notebook without placing them into subfolders.
I would now like to reflect the sub-package structure within the TOC, but it looks like one needs to put notebooks into subfolders for this to work?
Am I missing a trick on how to achieve this?
I tried to fool it by pointing the section name to the current path but it didn't like it:

format: jb-book
root: index
options:
  numbered: False
chapters:
- file: 00_config
- file: .
  title: PDS
  sections:
  - file: 02a_pds.indexes
  - file: 02b_pds.ctx_index
  - file: 02c_pds.apps

Any tips would be appreciated!

[choldgraf]

hmm - you should not need to put things in sub-folders in order to structure them in any particular way in Jupyter Book. Is it not working for you to just structure _toc.yml however you wish?

[michaelaye]

yeah, it looks like I was wrong, it doesn't need to be subfolders,
BUT apparently a section head needs to be a file?

So, in this case, I need to create a file for PDS:

chapters:
  - file: 00_config
  - file: PDS
    sections:
    - file: 02a_pds.indexes
    - file: -2b_pds.ctx_index

I was looking for a way where I do NOT need a file so to have a PDS "folder" in the TOC, because the nbdev system does not need that file for the sub-notebooks to be nested, but I might just as well create a little intro file for the TOC to work.
Thanks!

[choldgraf]

Ah - perhaps you are talking about this issue: executablebooks/sphinx-book-theme#460 ?

[michaelaye]

Well, not really, as that issue is about space-saving in the TOC it seems?

As I said, I'd like not to be forced to have an extra file named "PDS.md" just to have this layout in the TOC:

Instead, I'd like to be able to simply "name" that "PDS" TOC folder in the TOC, and then put my PDS-related notebooks underneath the section part in the TOC.
So, in other words, the "PDS" entry in the TOC would have no content file, but only serve as a structural element for the TOC.

[michaelaye]

So, is it true, that I need to create a basically empty file just to get sub-parts in the TOC?

[choldgraf]

If we get executablebooks/sphinx-book-theme#460 implemented, then you could make parts collapsible, which do not have to have a content file associated with them. But other than that, yes each page of a chapter/section must correspond to some content file. You cannot have a navigation entry that just serves as a container for more links, it must have some kind of content.

One thing we could try is to auto-generate these files via sphinx-external-toc. Maybe a flag could be used to generate the file under the hood so that Sphinx doesn't complain about a missing file or something? Maybe @chrisjsewell has thought about that?

[michaelaye]

Could it not be "path"-based maybe? In my example above, if the header for "PDS Indexes" would be "PDS/PDS Indexes", and the next would be "PDS/CTX Index", that kind of path would send the signal that a collapsible "PDS" entry with those 2 content files underneath is requested.

[choldgraf]

It might be possible to implement something like this, but that would require a non-trivial change in how we build the book structure. I think a more likely fix (that would still be a future enhancement, not possible now) would be to allow for a TOC structure that lets you nest sections underneath a chapter that has no content page, like:

- file: chapter1.md  # This chapter introduction has a dedicated content page
  sections:
  - file: ch1/section1.md
  - file: ch1/section2.md
- title: Chapter 2  # This chapter has no dedicated landing page, so we define just the title here
  sections:
  - file: ch2/section1.md
  - file: ch2/section2.md

But not sure exactly what makes sense there