Rename `items:` to `subtree:`

[choldgraf]

Right now, we use items: to define a single toctree object in a file. I think that because items: always maps onto one toctree, we should rename it simply to subtree so that users don't have to remember two different words.

So for example:

I think that this would reduce the number of words people need to remember, and it would make it clearer that subtrees: always contains a list of subtree: lists. I think this also makes it more technically precise, because subtree: always maps onto a single toctree directive (I think)

This is making the assumption that subtrees always contain a list of toctree objects, but I think that is a correct assumption as long as we want to strictly stick with Sphinx's underlying model, right?

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[chrisjsewell]

Ok interesting, yeh I'm not 100% on the items key name, but also couldn't think of a better name. I hadn't considered this one.

Do you think though it may be to difficult to distinguish the two though?

[choldgraf]

I think that if the subtree were anything other than "one of many subtrees in a list" then it would be confusing, but since subtree is always just "a list of subtree items", then subtree sounds more memorable and clear (to me).

[mmcky]

As you mention one nice attribute of using subtree is that it maps directly to the toctree directive which is more closely aligned with the underlying representation in sphinx.

My main question is then that subtrees is essentially the main toctree (in the sphinx context). You would never nest a subtrees right?

[chrisjsewell]

No subtrees is not the main toctree, it is a list of toctree within a file. You can add multiple toctree directives to any file, pseudo representation:

subtrees:

.. toctree:
   :option: value

   items:
   doc1
   glob1*
   https://example.com

.. toctree:
   :option: value

   items:
   doc3
   doc4

[choldgraf]

What if we go with what Sphinx does, and call them entries? That is perhaps slightly more specific than items, is generic enough that it can contain "globs, URLs, and files", and also makes a clean mapping onto the Sphinx docs.

so:

[mmcky]

thanks @chrisjsewell that is clear 👍

Probably a silly idea but is there a reason not to just use toctrees and toctree?

root: intro
toctrees:
  - toctree:
    - file:
  - toctree:
    - glob:

Perhaps a bit redundant / too literal and the items/entries is nicer to read.

[choldgraf]

Hmm that is certainly the most similar to how it'd look if you were writing it in rst or myst

[chrisjsewell]

is there a reason not to just use toctrees and toctree

It just feels abit weird to me, with respect to terminology, since essentially the whole file is the ToC tree, then (as shown in https://github.com/executablebooks/sphinx-external-toc/blob/main/toc-graphic.png) the subtrees are just that; sub-components of the whole tree. Then for toctree, this key doe not specify everything about the toctree, i.e. its options, merely the list of item/entries in it