Refactor the build system

scikit-image · Dec 3, 2021 · bb2a1e8 · bb2a1e8
1 parent 0c4e64d
commit bb2a1e8
Show file tree

Hide file tree

Showing 32 changed files with 60 additions and 29 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,8 +8,7 @@ _requirements.installed
 *~
 
 # Ignore built website
-site/_build
+book/_build
 
 # Ignore auto-generated content
-site/lectures
-
+book/_modules
diff --git a/Makefile b/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
+
diff --git a/README.md b/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).
diff --git a/site/Makefile → book/Makefile b/site/Makefile → book/Makefile
diff --git a/site/_static/favicon.png → book/_static/favicon.png b/site/_static/favicon.png → book/_static/favicon.png
diff --git a/site/_static/skimage-logo.png → book/_static/skimage-logo.png b/site/_static/skimage-logo.png → book/_static/skimage-logo.png
diff --git a/book/applications.md b/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
+```
diff --git a/site/conf.py → book/conf.py b/site/conf.py → book/conf.py
diff --git a/site/images → book/images b/site/images → book/images
diff --git a/site/index.md → book/index.md b/site/index.md → book/index.md
diff --git a/site/introduction.md → book/introduction.md b/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
-content/00_images_are_arrays
+_modules/tour_of_skimage
+_modules/00_images_are_arrays
 ```
diff --git a/content/00_images_are_arrays.md → modules/00_images_are_arrays.md b/content/00_images_are_arrays.md → modules/00_images_are_arrays.md
diff --git a/content/0_color_and_exposure.md → modules/0_color_and_exposure.md b/content/0_color_and_exposure.md → modules/0_color_and_exposure.md
diff --git a/content/2_feature_detection.md → modules/2_feature_detection.md b/content/2_feature_detection.md → modules/2_feature_detection.md
diff --git a/content/3_morphological_operations.md → modules/3_morphological_operations.md b/content/3_morphological_operations.md → modules/3_morphological_operations.md
diff --git a/content/4_segmentation.md → modules/4_segmentation.md b/content/4_segmentation.md → modules/4_segmentation.md
diff --git a/content/5_ransac.md → modules/5_ransac.md b/content/5_ransac.md → modules/5_ransac.md
diff --git a/content/6_sand_grain_counting.md → modules/6_sand_grain_counting.md b/content/6_sand_grain_counting.md → modules/6_sand_grain_counting.md
diff --git a/content/adv0_chromosomes.md → modules/adv0_chromosomes.md b/content/adv0_chromosomes.md → modules/adv0_chromosomes.md
diff --git a/content/adv1_lesion_quantification.md → modules/adv1_lesion_quantification.md b/content/adv1_lesion_quantification.md → modules/adv1_lesion_quantification.md
diff --git a/content/adv2_microarray.md → modules/adv2_microarray.md b/content/adv2_microarray.md → modules/adv2_microarray.md
diff --git a/content/adv3_panorama_stitching.md → modules/adv3_panorama_stitching.md b/content/adv3_panorama_stitching.md → modules/adv3_panorama_stitching.md
diff --git a/content/adv4_warping.md → modules/adv4_warping.md b/content/adv4_warping.md → modules/adv4_warping.md
diff --git a/content/adv5_pores.md → modules/adv5_pores.md b/content/adv5_pores.md → modules/adv5_pores.md
diff --git a/content/example_pano.md → modules/example_pano.md b/content/example_pano.md → modules/example_pano.md
diff --git a/content/machine_learning.md → modules/machine_learning.md b/content/machine_learning.md → modules/machine_learning.md
diff --git a/content/numpy_scipy_quiz.md → modules/numpy_scipy_quiz.md b/content/numpy_scipy_quiz.md → modules/numpy_scipy_quiz.md
diff --git a/content/other_libraries.md → modules/other_libraries.md b/content/other_libraries.md → modules/other_libraries.md
diff --git a/content/solutions_012.md → modules/solutions_012.md b/content/solutions_012.md → modules/solutions_012.md
diff --git a/content/stackoverflow_challenges.md → modules/stackoverflow_challenges.md b/content/stackoverflow_challenges.md → modules/stackoverflow_challenges.md
diff --git a/content/tour_of_skimage.md → modules/tour_of_skimage.md b/content/tour_of_skimage.md → modules/tour_of_skimage.md
diff --git a/site/applications.md b/site/applications.md