Closed choldgraf closed 3 years ago
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:
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?
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).
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?
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
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:
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.
Hmm that is certainly the most similar to how it'd look if you were writing it in rst or myst
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
Right now, we use
items:
to define a singletoctree
object in a file. I think that becauseitems:
always maps onto onetoctree
, we should rename it simply tosubtree
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 ofsubtree:
lists. I think this also makes it more technically precise, becausesubtree:
always maps onto a singletoctree
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?