Refactor the build system

.gitignore

@@ -1,14 +1,14 @@
 \#*
 .#*
 _requirements.installed
-build
 *.DS_Store
 *.html
 *.ipynb_checkpoints
 *.pyc
 *~
-*pano-advanced-output.png
-book/lessons
 
-# ignoring website local builds
-site/_build
+# Ignore built website
+book/_build
+
+# Ignore auto-generated content
+book/_modules

Makefile

@@ -1,42 +1,28 @@
-.PHONY: html
+.PHONY: clean book
 
-OBSHELL=/bin/bash
+.DEFAULT_GOAL = book
 
-.DEFAULT_GOAL = html
+NB_DIR = modules
+EXEC_NB_DIR = book/_modules
 
-LESSONS_DIR = lessons
-GENERATED_LESSONS_DIR = site/lessons
+MARKDOWNS = $(wildcard $(NB_DIR)/*.md)
+NOTEBOOKS = $(patsubst $(NB_DIR)/%.md, $(EXEC_NB_DIR)/%.ipynb, $(MARKDOWNS))
 
 _requirements.installed:
 	pip install -q -r requirements.txt
 	touch _requirements.installed
 
-MARKDOWNS = $(wildcard $(LESSONS_DIR)/*.md)
-MD_OUTPUTS = $(patsubst $(LESSONS_DIR)/%.md, $(GENERATED_LESSONS_DIR)/%.md, $(MARKDOWNS))
-NOTEBOOKS = $(patsubst %.md, %.ipynb, $(MD_OUTPUTS))
+$(EXEC_NB_DIR):
+	mkdir book/_modules
 
-.SECONDARY: $(MD_OUTPUTS) $(NOTEBOOKS)
+$(EXEC_NB_DIR)/%.ipynb:$(NB_DIR)/%.md $(EXEC_NB_DIR)
+	@# Jupytext will also catch and print execution errors
+	@# unless a cell is marked with the `raises-exception` tag
+	jupytext --execute --to ipynb --output $@ $<
 
-$(GENERATED_LESSONS_DIR)/%.ipynb:$(LESSONS_DIR)/%.md site/lessons site/lessons/images
-	# This does not work, due to bug in notedown; see https://github.com/aaren/notedown/issues/53
-	#notedown --match=python --precode='%matplotlib inline' $< > $@
-	notedown --match=python $< > $@
-	jupyter nbconvert --execute --inplace $@ --ExecutePreprocessor.timeout=-1
-
-%.md:%.ipynb
-	jupyter nbconvert --to=mdoutput --output="$(notdir $@)" --output-dir=$(GENERATED_LESSONS_DIR) $<
-#	$(eval NBSTRING := [📂 Download lesson notebook](.\/$(basename $(notdir $@)).ipynb)\n\n)
-#	sed -i'.bak' '1s/^/$(NBSTRING)/' $@
-
-site/lessons:
-	mkdir -p book/lessons
-
-site/lessons/images:
-	ln -s ${PWD}/lessons/images ${PWD}/site/lessons/images
-
-html: site/lessons _requirements.installed $(NOTEBOOKS) $(MD_OUTPUTS)
-	@export SPHINXOPTS=-W; make -C site html
-	cp $(GENERATED_LESSONS_DIR)/*.ipynb book/build/html/lessons/
+book: _requirements.installed $(NOTEBOOKS)
+	@export SPHINXOPTS=-W; make -C book html
 
 clean:
-	rm -rf $(GENERATED_LESSONS_DIR)/*
+	make -C book clean
+

README.md

@@ -1,5 +1,4 @@
-scikit-image tutorials
-======================
+# scikit-image tutorials
 
 A collection of tutorials for the [scikit-image](http://skimage.org) package.
 
@@ -16,8 +15,7 @@ Refer to [the gallery](http://scikit-image.org/docs/dev/auto_examples/) as
 well as [scikit-image demos](https://github.com/scikit-image/skimage-demos)
 for more examples.
 
-Usage
------
+## Usage
 
 These usage guidelines are based on goodwill. They are not a legal contract.
 
@@ -42,9 +40,28 @@ For more information on these guidelines, which are sometimes known as
 CC0 (+BY), see [this blog post](http://www.dancohen.org/2013/11/26/cc0-by/) by
 Dan Cohen.
 
-Contributing
-------------
+## Contributing
 
 If you make any modifications to these tutorials that you think would benefit
 the community at large, please
 [create a pull request](http://scikit-image.org/docs/dev/contribute.html)!
+
+The tutorials live at
+https://github.com/scikit-image/skimage-tutorials
+
+
+## Contributor notes
+
+- Notebooks are stored in `modules`; see [modules/00_images_are_arrays.md](modules/00_images_are_arrays.md)
+  for an example.
+- They use the [myst](https://myst-nb.readthedocs.io/en/latest/)
+  notebook format
+- Cells can be tagged with:
+  `remove-input` : Get rid of the input but display the output
+  `remove-output` : Show the input but not the output
+  `raises-exception` : This cell is expected to fail execution, so
+  don't halt the book build because of it.
+
+To build the book, run `make`. Results appear in `book/_build`.
+Notebooks can be edited in your favorite text editor or in Jupyter (as
+long as Jupytext is installed).

site/Makefile → book/Makefile

@@ -1,5 +1,4 @@
-# Minimal makefile for Sphinx documentation
-#
+.PHONY: help Makefile clean
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
@@ -12,18 +11,10 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-notebooks:
-	mkdir -p notebooks
-	jupytext -k python3 ../content/*.md --from myst --to notebook
-	mv ../content/*.ipynb notebooks
-
 clean:
 	rm -rf _build
-	rm -rf notebooks
-
-.PHONY: help Makefile notebooks clean
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

book/applications.md

@@ -0,0 +1,15 @@
+# scikit-image applications
+
+A collection of tutorials highlighting the use of scikit-image for applications in science.
+
+```{toctree}
+---
+maxdepth: 1
+---
+_modules/adv0_chromosomes.md
+_modules/adv1_lesion-quantification.md
+_modules/adv2_microarray.md
+_modules/adv3_panorama_stitching.md
+_modules/adv4_warping.md
+_modules/adv5_pores.md
+```

site/conf.py → book/conf.py

@@ -31,6 +31,7 @@
     'myst_nb',
     'sphinx_copybutton',
 ]
+jupyter_execute_notebooks = "off"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -67,4 +68,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static']

site/index.md → book/index.md

@@ -4,7 +4,7 @@
 
 [launch_binder]: http://mybinder.org/v2/gh/scikit-image/skimage-tutorials/main?urlpath=lab/tree/content
 
- ## Content
+## Content
 
 ```{toctree}
 ---
@@ -14,9 +14,8 @@ introduction
 applications
 ```
 
-
 ## Indices and tables
 
 * {ref}`genindex`
 * {ref}`modindex`
-* {ref}`search`
+* {ref}`search`

site/introduction.md → book/introduction.md

@@ -6,6 +6,6 @@ Basic tutorials to prepare you for your journey on scikit-image.
 ---
 maxdepth: 1
 ---
-content/tour_of_skimage.md
-content/00_images_are_arrays.md
-```
+_modules/tour_of_skimage
+_modules/00_images_are_arrays
+```