search

executablebooks / sphinx-external-toc

A sphinx extension that allows the site-map to be defined in a single YAML file
https://sphinx-external-toc.readthedocs.io
MIT License
33 stars 18 forks source link

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

Closed choldgraf closed 3 years ago

choldgraf commented 3 years ago

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 commented 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

choldgraf commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

choldgraf commented 3 years ago

would break all CLI functionality

Could you explain this? What would break if:

?

choldgraf commented 3 years ago

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 commented 3 years ago

To quote https://github.com/executablebooks/sphinx-external-toc/issues/28#issuecomment-822811707

explicit is better than implicit

chrisjsewell commented 3 years ago

I did jupyter-book build mybook

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

choldgraf commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

choldgraf commented 3 years ago

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

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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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)