Toc numbering is weird when using defaults: numbered: true

[AakashGfude]

When I use

defaults:
  numbered: true

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:

[chrisjsewell]

Yeh you shouldn’t use defaults for numbering you should use options:

options:
  numbered: true

[chrisjsewell]

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

[AakashGfude]

@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.

[choldgraf]

I believe that defaults: will effectively add the numbered: true option to all nested toctrees, whereas options will apply only to the top-level toctrees (which is why options is the correct one to use here).

[AakashGfude]

@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?

[AakashGfude]

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

[AakashGfude]

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.

[chrisjsewell]

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

[mmcky]

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.

[chrisjsewell]

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

[choldgraf]

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

[mmcky]

@choldgraf I have added some further details to jupyter-book/jupyter-book#1326

• update sphinx-external-toc to issue a warning

[mmcky]

duplicate of #45