Remove the "options" shorthand

[choldgraf]

In the README we define a shortcut to include options with a sub-tree even though we are using the shorthand notation:

or, if you are using the shorthand for a single subtree, set options under an options key:

root: intro
options:
  caption: Subtree Caption
  hidden: False
  maxdepth: 1
  numbered: True
  reversed: False
  titlesonly: True
items:
- file: doc1
  options:
    titlesonly: True
  items:
  - file: doc2

I'd be inclined to just force people to use the "verbose" subtrees method, rather than special casing a new keyword:

root: intro
subtrees:
- caption: Subtree Caption
  hidden: False
  maxdepth: 1
  numbered: True
  reversed: False
  titlesonly: True
  items:
  - file: doc1
    subtrees:
    - items:
      - file: doc2
      titlesonly: True

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 ?

[chrisjsewell]

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

[choldgraf]

That's a good point

[choldgraf]

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" 🤔🤔🤔

[choldgraf]

let's just keep it as-is, I agree it's nicer to not force people to use part: in jupyter book