Closed choldgraf closed 3 years ago
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
@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?
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
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
Users either use the default key mapping, or the format
key, that's the only options that'll I'll entertain
would break all CLI functionality
Could you explain this? What would break if:
format:
via conf.py
jb-book
by defaultformat:
keyjupyter-book build mybook
?
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.
To quote https://github.com/executablebooks/sphinx-external-toc/issues/28#issuecomment-822811707
explicit is better than implicit
I did jupyter-book build mybook
I'm not talking about jupyter-book build, I'm talking about the cli in this package
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.
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
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.
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 https://github.com/executablebooks/sphinx-external-toc/issues/1#issuecomment-822060693
In a conversation @chrisjsewell pointed out that we basically already have two different kinds of documents defined with Jupyter Book's _toc.yml
:
root -> parts -> chapters -> sections
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
@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:
_toc.yml
drives the website, and _toc_book.yml
drives the pdfthis 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.
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)
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.
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
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)
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
inconf.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"
inconf.py
as well?