Closed choldgraf closed 3 years ago
this was added with jupyter-book in mind, for setting numbering:
format: jb-book
options:
numbered: true
root: index
chapters:
- file: content1
- file: subfolder/index
sections:
- file: subfolder/asubpage
numbering shouldn't be set in defaults
because (as is mentioned in the README) sphinx then logs a warning if you have nested toctrees.
Otherwise, you will be forcing people to always have parts if they want to use numbering:
format: jb-book
root: index
parts:
- numbered: true
chapters:
- file: content1
- file: subfolder/index
sections:
- file: subfolder/asubpage
of for an article:
format: jb-article
root: index
subtrees:
- numbered: true
sections:
- file: content1
- file: subfolder/index
sections:
- file: subfolder/asubpage
That's a good point
hmmm - do we think "always forcing people to have parts" is that bad? It feels like it could fit under "explicit is better than implicit" 🤔🤔🤔
let's just keep it as-is, I agree it's nicer to not force people to use part:
in jupyter book
In the README we define a shortcut to include options with a sub-tree even though we are using the shorthand notation:
I'd be inclined to just force people to use the "verbose" subtrees method, rather than special casing a new keyword:
Since we require more "verbosity" in the case of specifying options (via introducing a new keyword), I feel like we might as well just use re-use a pre-existing verbose structure, rather than defining a new one. What do you think @chrisjsewell ?