Skip to content

Update toc using jb toc migrate. #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 19, 2022
Merged

Update toc using jb toc migrate. #65

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions _toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
- file: lectures/00_images_are_arrays
format: jb-article
root: lectures/00_images_are_arrays
sections:
Comment on lines +1 to +3
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to prefer simpler, so I'm 👍 ; but let's also hear what the others think.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@stefanv stefanv Sep 21, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am happy to go with a "whoever does the work gets to decide" approach :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok but it's "whoever". =P

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, fixed.

- file: lectures/1_image_filters
- file: lectures/3_morphological_operations
- file: lectures/4_segmentation
- file: lectures/three_dimensional_image_processing