Is there a way to specify format: without putting it in the yml file?

[choldgraf]

I like the idea of defining "schemas" that can provide more "reader-facing words" (like "part" and "chapter") which @chrisjsewell added via the format key. One challenge with this is that it'll require all Jupyter Book users to add that key to the top of their _toc.yml file.

It seems like another approach could be to allow for people to specify format in conf.py. In this case, Jupyter Book could set this configuration for people, and then they wouldn't have to add this to their TOC layout.

One downside of this is that information that defines the _toc.yml schema, and the toctree structure itself, would now be in two different places.

Curious if @chrisjsewell thought about this, or had strong opinions one way or another. If there aren't strong opinions, perhaps we could allow for toc_format = "jb-article" in conf.py as well?

[chrisjsewell]

One downside of this is that information that defines the _toc.yml schema, and the toctree structure itself, would now be in two different places.

Yeh this is why I'm completely against it, the file would essentially be unreadable without it

[choldgraf]

@chrisjsewell unreadable outside the sphinx site context itself - do you imagine that somebody would want to read one of these files, and understand the "key1 -> key2" mapping, outside of the Sphinx build that the _toc.yml is associated with?

[choldgraf]

To put it from a user's perspective, I think that a Jupyter Book user doesn't care about that format: key - it is just an implementation detail about the library that Jupyter Book uses to define its TOC structure. So similar to how Jupyter Book tries to "abstract away" Sphinx-specific configuration (at least, by default), I'm trying to imagine how sphinx-external-toc-specific configuration could also be abstracted away

[chrisjsewell]

Unreadable programmatically and would break all CLI functionality.

It's basically the same discussion we've had with the coexistence of sphinx.yaml and conf.py

[chrisjsewell]

Users either use the default key mapping, or the format key, that's the only options that'll I'll entertain

[choldgraf]

would break all CLI functionality

Could you explain this? What would break if:

• You could set format: via conf.py
• Jupyter Book set this to jb-book by default
• A user did not provide their own format: key
• I did jupyter-book build mybook

?

[choldgraf]

I am worried that we are straying from one of the principles of our design here:

Users should not need to know anything about the build system. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, and so on should not be a requirement. They should only need to use a simple tool to control the process.

So if we stray from that, I wanna make sure we have a strong reason for doing so.

[chrisjsewell]

To quote #28 (comment)

explicit is better than implicit

[chrisjsewell]

I did jupyter-book build mybook

I'm not talking about jupyter-book build, I'm talking about the cli in this package

[choldgraf]

As a Jupyter Book user, is it useful for me to see the format: jb-book key in _toc.yml? (assuming that the Jupyter Book user knows that _toc.yml is sitting in a filesystem alongside their book that they control and have access to, and they build the book with jupyter-book build mybook/. That is 99.9% of our users)

Something that might make this format: key a useful option is if we want users to change it, in order to use different kinds of _toc.yml structures. Is that something that @mmcky imagined? (e.g., I have seen jb-article thrown around which is an interesting idea). If we can turn this into a feature instead of an implementation detail, then I think it'd be reasonable to have in there.

[chrisjsewell]

I have seen jb-article thrown around which is an interesting idea

What? I think you need to read the README again, this is already a format: users have to choose between this or jb-book, this is why it needs to be in the toc

[choldgraf]

Right - it's in the README of this repository but I'm wondering if this is a feature that anybody has requested or discussed before (e.g., is there an issue where we discuss this?). To my knowledge this format doesn't already exist in jupyter-book, it would be introducing something new. I am trying to understand if this is something that users want or need, that should be our driving principle for what we build.

[chrisjsewell]

To my knowledge this format doesn't already exist in jupyter-book, it would be introducing something new.

Yes it does already exist, this is exactly why I added it.
It defines whether the top level key is sections or chapters.
I suggest you look at the migration test files that I have already linked to in #1 (comment)

[choldgraf]

In a conversation @chrisjsewell pointed out that we basically already have two different kinds of documents defined with Jupyter Book's _toc.yml:

• Books: root -> parts -> chapters -> sections
• Articles (or single-chapter books I guess): root -> sections

And this is a way to explicitly disambiguate them.

I think this is a reasonable rationale for adding a format: config. So I'm fine requiring users to see this if it'll help them + us disambiguate what is the structure of a book

[mmcky]

@choldgraf My thoughts on format are that it would be optional if using the general syntax and only required if you want to use one of the schema's that are defined. However, my feeling is that most users will use a schema as an entry point so it will be pretty common.

@chrisjsewell I have seen a migration tool. Will this translate to the current _toc.yml to the general schema?

I think it is good to have the toc config / schema definition in one place.

---

One aspect of the format / domain elements I have been thinking about is the possibility of having two _toc.yml files where:

1. _toc.yml drives the website, and
2. _toc_book.yml drives the pdf

this would allow the pdf to be built using the book/article schema while leaving flexibility to define the companion website. I haven't fully developed this idea but just wanted to mention this as it may be relevant to how we get jupyter-book to read these toc files.

FWIW - I think we should focus on having a single _toc.yml that derives all outputs from a common source but this idea is really about providing an optional route for flexibility to determine the structure of different outputs (more specifically) in the future.

[chrisjsewell]

I have seen a migration tool. Will this translate to the current _toc.yml to the general schema?

It migrates a current jupyterbook toc to the most suitable format of jb-book or jb-article (see the tests)

[mmcky]

It migrates a current jupyterbook toc to the most suitable format of jb-book or jb-article (see the tests)

Well that is cool. I'll checkout the tests.

[chrisjsewell]

Yeh and in the jupyterbook PR it checks whether the toc is valid (e.g. if it has not been migrated) and points users towards the migrate command

[chrisjsewell]

and as a concluding point here, a key design principle is that "the toc must be (programatically) readable as a standalone file".
This allows it to be something that is not "strictly" tied to sphinx, and for additional CLI functionality (like validation and migrations) with the toc file as the only required input (you don't have to have added complexity of finding/reading the conf.py or jupyterbook's _config.yml)