Refactor the build system

Author: stefanv

.gitignore

@@ -8,8 +8,7 @@ _requirements.installed
 *~
 
 # Ignore built website
-site/_build
+book/_build
 
 # Ignore auto-generated content
-site/lectures
-
+book/_modules

Makefile

@@ -1,13 +1,28 @@
-.PHONY: clean html
+.PHONY: clean book
 
 .DEFAULT_GOAL = book
 
+NB_DIR = modules
+EXEC_NB_DIR = book/_modules
+
+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
 
-book: _requirements.installed
+$(EXEC_NB_DIR):
+	mkdir book/_modules
+
+$(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 $@ $<
+
+book: _requirements.installed $(NOTEBOOKS)
 	@export SPHINXOPTS=-W; make -C book html
 
 clean:
-	rm -rf book/_build
+	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 renamed to book/Makefile

@@ -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
+```