1.1.0: missing examples for several use cases root-without-subtree, parallel-subtree

[n8willis]

Describe the bug

Working with release 1.1.0, I find that there are several TOC scenarios where there is not an example in the documentation, leaving it to trial-and-error to figure out how to declare a valid _toc.yml (or even if it is possible to do so).

example
All of the example TOCtrees on the doc site begin with a subtree attached to root, like so:

root: intro
subtrees:
- entries:
  - file: doc1
    title: Document 1 Title
  - url: https://example.com
    title: Example URL Title

It is not clear how to define a TOCtree that has, for example, a subtree on the second element but not on the root element. Just doing:

root:intro
file: overview
file: tutorial
subtrees:
- entries:
  - file: left-tutorial
  - file: right-tutorial

raises an Extension error: [etoc] Unknown keys found: {'file'}, allowed: {'format', 'defaults', 'root', 'options', 'title', 'subtrees', 'entries', 'meta'} @ '/'

Is a subtree on root mandatory? Do you have to define entries on root? What keys can you set on root outside of the subtrees elements? The documentation only discusses keys within a subtrees element block.

example 2

The examples in the documentation page show several instances of a subtree nested below another subtree, but they do not show an example of two subtrees existing at the same level. That is, results that look like:

Menu topic
- Subtree number 1
  - subtree-1 page one
  - subtree-1 page two
- Subtree number 2
  - subtree-2 page a
  - subtree-2 page b
  - subtree-2 page c

Here again, the naive approach you might try first, based on the examples in the documentation, suggests that each subtree at a certain level requires its own entries, a la:

- file: menutopic
  title: Menu topic
  subtrees:
  - caption: Subtree number 1
    entries:
    - file: subtree1pg1
    - file: subtree1pg2
  - caption: Subtree number 2
    entries:
    - file: subtree2pga
    - file: subtree2pgb
    - file: subtree2pgc

But that also raises Extension errors, of the form [etoc] entry not a mapping containing 'entries' key @ '//entries/1/subtrees/2/' or else [etoc] while parsing a block mapping in "/home/user/sphinx-documents/_toc.yml", line 70, column 3 expected <block end>, but found '-'

(depending a bit on where in the overall TOC structure the arrangement appears, I believe.

problem
This is a problem for people creating their own TOCtrees because the structure of the TOCtree has to accurately reflect the documents, and if the documents need a subtree on the second element only, or the documents need to have two subtrees on the same level, then the user is stuck without a way out.

Reproduce the bug

Create a _toc.yml file that has no subtrees on root but has a subtree (or two subtrees) on a subsequent entry.

List your environment

Sphinx 8.1.3
sphinx_external_toc 1.1.0
alabaster 1.0.0

Python 3.10.12