Update toc using jb toc migrate. #65
Conversation
| format: jb-article | ||
| root: lectures/00_images_are_arrays | ||
| sections: |
There was a problem hiding this comment.
| format: jb-article | |
| root: lectures/00_images_are_arrays | |
| sections: | |
| format: jb-book | |
| root: lectures/00_images_are_arrays | |
| chapters: |
I think I'd like this repo to more closely resemble a book. See discussion at jupyter-book/jupyter-book#1355 (comment)
Probably we'll need a different index page but 🤷 that can be a different PR
There was a problem hiding this comment.
I'm not familiar with the distinctions, so I have no opinion! This PR is just the result of running the recommended jupyterbook migrate command, so the output is likely pretty generic.
While we're on the topic - I wanted to gauge interest in investigating a sphinx-based workflow instead. I've had some experience helping to set up related sites for NumPy (site, source) and NetworkX (site, source), and have found the sphinx-based workflow pretty straightforward for setting things up. I know we've had a brief discussion on this elsewhere, but AIUI jupyter-book is a thin wrapper on top of the other lower-level executablebook projects that include sphinx extensions like myst-nb. Jupyter-book introduces a layer of indirection for things like the configuration and toc which I believe are designed to be more user-friendly for users who have never used sphinx, but are unnecessary if you are comfortable with a sphinx workflow.
Anyways - I'd be happy to put together a draft PR to illustrate what this could look like, with the understanding that it would only be for illustration purposes and it might not necessarily be adopted. I don't want to step on any toes however: if there is a strong preference for sticking with the current workflow I'm happy to leave off!
There was a problem hiding this comment.
I tend to prefer simpler, so I'm 👍 ; but let's also hear what the others think.
There was a problem hiding this comment.
While we're on the topic - I wanted to gauge interest in investigating a sphinx-based workflow instead.
I completely forgot that @alexdesiqueira has done this already! I'll switch my focus over to #59. Thanks @hmaarrfk for the reminder.
There was a problem hiding this comment.
Jupyter-book introduces a layer of indirection for things like the configuration and toc which I believe are designed to be more user-friendly for users who have never used sphinx
🙋
Honestly I have never grokked sphinx despite "using it" in many projects. I cargo-cult the whole workflow, and I hate it. JB marked the first time that I felt comfortable using a sphinx-based tool.
So, I do actually have a strong preference for using JB unless straight sphinx gives a concrete advantage that we are lacking. (ie I don't want to hear "configurability", I want to hear "we want to harmonize the styling of the home page and the tutorials and JB makes that very very hard/impossible".)
There was a problem hiding this comment.
Yes, the markdown documents will then get executed using something like:
jupytext --to notebook --execute notebook.md
What I'm saying about Sphinx is that there really isn't configuration that needs to be done. You just produce the executed markdown and compile the site. I'm not against using another tool if it contributes something other than configuration for features we don't use.
There was a problem hiding this comment.
Yes, the markdown documents will then get executed using something like:
jupytext --to notebook --execute notebook.md
Yeah, for a non-executablebooks-based workflow I think jupytext would definitely be the way to go. You'd miss out on the automatic execution caching provided by jupyter-cache, but that's very easy to replicate if you're using make (AFAIK jupyter-cache only does execution caching at the file-level, not individual notebook cells).
So, I do actually have a strong preference for using JB unless straight sphinx gives a concrete advantage that we are lacking. (ie I don't want to hear "configurability", I want to hear "we want to harmonize the styling of the home page and the tutorials and JB makes that very very hard/impossible".)
In principle everything that is possible with the sphinx-only workflow is also possible with jupyter-book, so there should be no difference between what's possible with one interface versus the other. IME nothing is "very very hard", just different :) I have experienced some warts with jupyter-book's config/toc specs, particularly with other builders (see e.g. jupyter-book/jupyter-book#1192), but these are always promptly fixed and issues have become far less frequent as jb has matured.
There was a problem hiding this comment.
I am happy to go with a "whoever does the work gets to decide" approach :)
|
I'm taking the liberty to approve and merge this in anticipation of EuroSciPy 2022. That does not mean I endorse this approach over the ones proposed in #59 or #66. Although I'm heavily in favor of migrating away from the ipynb format. What I like about jupytext is the nice text format that can be opened as a Python script if configured such and that the hurdle to open it as a notebook is not that big. |
Closes #64
At least gets the jupyter-book workflow running. There are still failures in the build process, but it at least gets the build running.
This is the result of running
jb toc migrateas recommended at the very end of the error message posted in #64 (I missed this in the first readthrough of the error).