Replacing sphinx-external-toc with a custom Python script

[michaelosthege]

Motivation

Before I can fully commit to writing with Jupyter book, I need to resolve the most important blocker which is the overall composition of a scientific article:

• No blank pages from the start
• No ToC page
• Un-numbered sections for "Abstract", "Acknowledgements" and "References"

(rendered with pdflatex)

Status

At this point I fiddled with _toc.yml for an accumulated >16 hours, but I have not tamed it to solve any of the above points.

• With jb-book format I couldn't get rid of "Chapter"s.
• With jb-article I run into jb-articles contains no top level headings jupyter-book/jupyter-book#1552
• The hidden: true setting did not have an effect.
• The numbered: false setting did not have an effect (with sphinx-multitoc-numbering in _config.yml/sphinx/config/extra_extensions)

jb-book based _toc.yml

format: jb-book
root: index
chapters:
- file: 0_Prefix/prefix.md
- file: 1_Introduction/introduction.md
- file: 2_Implementation/implementation.md
- file: 3_Application/application.md
- file: 4_Conclusion/conclusion.md
- file: 5_Suffix/suffix.md

jb-article based _toc.yml

format: jb-article
root: index
sections:
- file: 0_Prefix/prefix.md
- file: 1_Introduction/introduction.md
- file: 2_Implementation/implementation.md
- file: 3_Application/application.md
- file: 4_Conclusion/conclusion.md
- file: 5_Suffix/suffix.md

raw _toc.yml with extra settings

defaults:
  titlesonly: true
  hidden: true
  numbered: true
root: index
subtrees:
- caption: Prefix
  numbered: false
  entries:
  - file: 0_Prefix/prefix.md
- caption: Main
  entries:
  - file: 1_Introduction/introduction.md
  - file: 2_Implementation/implementation.md
  - file: 3_Application/application.md
  - file: 4_Conclusion/conclusion.md
- caption: Suffix
  numbered: false
  entries:
  - file: 5_Suffix/suffix.md

I wouldn't be surprised if some settings in the above YAML don't have an effect because I put them in the wrong place or indentation..

Procedure

My ToC experience is probably best described as performing a minimally invasive surgery without a camera:
Trying to control the sphinx_external_toc.api.SiteMap and sphinx.environment.Buildenvironment.toc_secnumbers by writing a YAML file which jb parses as a special format, maps it onto another YAML "schema" which is again parsed into a SiteMap.
And somehow the numbered settings must survive that procedure such that sphinx-multitoc-numbering can know how to do the numbering.

Did I grasp that correctly?

Question

(How) can I do a jb build without going through the YAML bottleneck?

For example, instead of _toc.yml + sphinx-external-toc + sphinx-multitoc-numbering, I would prefer to write a toc.py.

There I could import sphinx_external_toc, sphinx_multitoc_numbering and create the SiteMap directly.
Also the partial numbering could then be achieved with a simple exclusion list, right?

[chrisjsewell]

Heya @michaelosthege, if you are wishing to fully replace sphinx-external-toc, why not use "jupyter-book" as its component sphinx extensions?

Simply run jb config sphinx on your book, and it will output the conf.py that you can use directly with sphinx-build.

Then you could fork https://github.com/executablebooks/sphinx-external-toc and play around with extending/modifying it in some way, to resolve your needs. (same for sphinx_multitoc_numbering)

Then, hopefully, when you have some working modifications, you can propose them on the main branch.
Then we can feed this back up in to jupyter-book.