Closed AakashGfude closed 3 years ago
Yeh you shouldn’t use defaults for numbering you should use options:
options:
numbered: true
This is already warned about in the sphinx-external-toc documentation: https://sphinx-external-toc.readthedocs.io/en/latest/user_guide/sphinx.html#toc-tree-options
Can you make sure it’s correct in the jupyter-book documentation
@chrisjsewell Yes, I did read about that warning. But I think options
can be used only at the level of a subtree. I was trying it in jupyter-book
docs which has multiple parts as child tocs. I could not find any global way of numbering apart from the defaults
key for that configuration.
I believe that defaults:
will effectively add the numbered: true
option to all nested toctree
s, whereas options will apply only to the top-level toctree
s (which is why options
is the correct one to use here).
@choldgraf in the case of projects with multiple parts like jb docs, if I use options in the top root level, the numbering does not take effect, I have to individually number each part. As options work on the subtree level. https://github.com/executablebooks/sphinx-external-toc#toc-tree-options .
So is it encouraged to number each individual subtrees explicitly, instead of having a global numbering that numbers all subtrees?
Can you make sure it’s correct in the jupyter-book documentation
@chrisjsewell should we remove the defaults: numbered: true section from the jb doc then? https://github.com/executablebooks/jupyter-book/blob/master/docs/structure/configure.md#number-your-chapters-and-sections
Yeh you shouldn’t use defaults for numbering you should use options:
options: numbered: true
This does not work on the root-level of jb docs as I have mentioned in the comments above. It only works with individual parts.
So is it encouraged to number each individual subtrees explicitly, instead of having a global numbering that numbers all subtrees?
basically yep. Obviously you are welcome to submit a PR to sphinx-external-toc to propose any improvements to this; but it is just a shortcoming of sphinx, that you cannot add numbering to all nested subtrees without it complaining
Can you make sure it’s correct in the jupyter-book documentation
@chrisjsewell should we remove the defaults: numbered: true section from the jb doc then? https://github.com/executablebooks/jupyter-book/blob/master/docs/structure/configure.md#number-your-chapters-and-sections
Hey @AakashGfude - Yes we should remove that from the docs and encourage numbering all parts for chapter/part
structures.
there probably is a way to code it into sphinx-external-toc, its just not trivial. also perhaps there should be a warning if someone does put numbering in the defaults
I'm a +1 on just putting a warning if numbered
is in the defaults.
@AakashGfude I'm happy to review a PR to the docs that clarifies this and shows the proper way to do numbering
@choldgraf I have added some further details to executablebooks/jupyter-book#1326
sphinx-external-toc
to issue a warningduplicate of #45
When I use
globally in
_toc.yml
, some of the files are not numbered. And this changes with the number of times I run the build.The screenshot is when I ran the build the first time:
The warnings I got during the build: