Bump jupyter-book from 1 to 2 (#74)

Author: tsalo

.gitignore

@@ -3,7 +3,9 @@ data/
 _build/
 
 # Generated figures (copied to docs/_images/ by Sphinx during build)
-content/figures/
+content/figures/*
+!content/figures/
+!content/figures/*animation.gif
 
 .DS_Store
 

Makefile

@@ -2,13 +2,17 @@
 # `uv` honors UV_PROJECT_ENVIRONMENT to place the venv somewhere other than .venv.
 export UV_PROJECT_ENVIRONMENT := meda
 
+# GitHub Pages serves this repository as a project site under this path.
+# MyST/Jupyter Book 2 uses BASE_URL to prefix CSS, JS, images, JSON, and route links.
+PAGES_BASE_URL ?= /multi-echo-data-analysis
+
 # Reproducible image outputs: matplotlib honors SOURCE_DATE_EPOCH and will stamp
 # PNGs with a fixed timestamp instead of "now", so identical plots produce
 # identical bytes (and identical content-hashed filenames in _images/).
 # 1577836800 == 2020-01-01T00:00:00Z
 export SOURCE_DATE_EPOCH := 1577836800
 
-.PHONY: help check-env book clean serve sync-docs site-publish install runall build site
+.PHONY: help check-env book clean serve sync-docs site-publish install runall build preview-docs
 
 help:
 	@echo "Please use 'make <target>' where <target> is one of:"
@@ -17,9 +21,9 @@ help:
 	@echo "  book        to activate 'meda' and build the Jupyter Book into _build/"
 	@echo "  clean       to clean out site build files"
 	@echo "  runall      to run all notebooks in-place, capturing outputs with the notebook"
-	@echo "  serve       to serve the repository locally with Jekyll"
-	@echo "  build       to build the site HTML and store in _site/"
-	@echo "  site        to build the site HTML, store in _site/, and serve with Jekyll"
+	@echo "  serve       to build and serve the site locally at http://localhost:3000"
+	@echo "  build       to build the site HTML into _build/html/"
+	@echo "  preview-docs to serve committed docs/ files at the GitHub Pages base path"
 	@echo "  sync-docs   to copy _build/html into docs/ for GitHub Pages"
 	@echo "  site-publish to build the book and sync docs/ (book + sync-docs)"
 
@@ -35,25 +39,24 @@ check-env:
 
 # Activate the 'meda' environment (via `uv run`) and build the book.
 book: check-env
-	uv run --locked jupyter-book build ./
+	BASE_URL=$(PAGES_BASE_URL) uv run --locked jupyter-book build --html --execute
 
 sync-docs:
-	python scripts/sync_docs.py
+	uv run --locked python scripts/sync_docs.py
 
 site-publish: book sync-docs
 
 runall:
 	jupyter-book run ./content
 
 clean:
-	python scripts/clean.py
+	uv run --locked python scripts/clean.py
 
-serve:
-	bundle exec guard
+serve: check-env
+	uv run --locked jupyter-book start
 
 build: check-env
-	uv run --locked jupyter-book build ./
+	BASE_URL=$(PAGES_BASE_URL) uv run --locked jupyter-book build --html --execute
 
-site: build
-	bundle exec jekyll build
-	touch _site/.nojekyll
+preview-docs:
+	uv run --locked python scripts/serve_docs.py

_config.yml

@@ -20,7 +20,6 @@ parts:
     - file: content/fMRI_Sequences
     - file: content/Signal_Decay
     - file: content/TE_Dependence
-    - file: content/plot_approach_figures.md
   - caption: Practical Resources
     chapters:
     - file: content/Multi_Echo_Datasets
@@ -36,6 +35,7 @@ parts:
     - file: content/06_Cerebrovascular_Reactivity_Mapping.md
     - file: content/07_Manual_Classification_with_rica.md
     - file: content/08_ICA_Based_Denoising.md
+    - file: content/09_Advanced_Applications.md
   - caption: Final Thoughts
     chapters:
     - file: content/bibliography.md

_toc.yml

@@ -76,7 +76,7 @@ glue_figure("figure_t2starmap", fig, display=False)
 :name: "figure_t2starmap"
 :align: center
 
-T2* map estimated from multi-echo data using tedana's {py:func}`~tedana.workflows.t2smap_workflow`.
+T2* map estimated from multi-echo data using tedana's {external+tedana:py:func}`~tedana.workflows.t2smap_workflow`.
 ```
 
 ```{code-cell} ipython3
@@ -102,7 +102,7 @@ glue_figure("figure_s0map", fig, display=False)
 :name: "figure_s0map"
 :align: center
 
-S0 map estimated from multi-echo data using tedana's {py:func}`~tedana.workflows.t2smap_workflow`.
+S0 map estimated from multi-echo data using tedana's {external+tedana:py:func}`~tedana.workflows.t2smap_workflow`.
 ```
 
 ```{code-cell} ipython3

content/01_Optimal_Combination_with_t2smap.md

@@ -12,7 +12,7 @@ kernelspec:
 
 # Volume-wise T2*/S0 estimation with `t2smap`
 
-Use {py:func}`tedana.workflows.t2smap_workflow` {cite:p}`DuPre2021` to calculate volume-wise T2*/S0,
+Use {external+tedana:py:func}`tedana.workflows.t2smap_workflow` {cite:p}`DuPre2021` to calculate volume-wise T2*/S0,
 as in {cite:t}`power2018ridding` and {cite:t}`heunis2021effects`.
 
 ```{code-cell} ipython3

content/02_Volume-wise_T2star_estimation_with_t2smap.md

@@ -14,7 +14,7 @@ kernelspec:
 
 In this analysis tutorial, we will use `tedana` {cite:p}`DuPre2021` to perform multi-echo denoising.
 
-Specifically, we will use {py:func}`tedana.workflows.tedana_workflow`.
+Specifically, we will use {external+tedana:py:func}`tedana.workflows.tedana_workflow`.
 
 ```{code-cell} ipython3
 import json

content/03_Denoising_with_tedana.md

@@ -18,7 +18,8 @@ To remove noise from your data, you can regress the "bad" components out of it,
 
 Let's start by loading the necessary data.
 
-````{tab} Python
+:::::{tab-set}
+::::{tab-item} Python
 ```python
 import numpy as np
 import pandas as pd
@@ -44,30 +45,32 @@ arr = arr.T
 # The first dimension should be time
 assert arr.shape[1] == mixing.shape[0]
 ```
-````
-````{tab} FSL
+::::
+::::{tab-item} FSL
 ```bash
 data_file=preprocessed_data.nii.gz
 mixing_file=mixing.tsv
 mask_file=mask.nii.gz
 den_idx=(0, 1, 2, 3, 4, 5)
 ```
-````
-````{tab} AFNI
+::::
+::::{tab-item} AFNI
 ```bash
 data_file=preprocessed_data.nii.gz
 mixing_file=mixing.tsv
 mask_file=mask.nii.gz
 den_idx=(0, 1, 2, 3, 4, 5)
 ```
-````
+::::
+:::::
 
 ## Aggressive Denoising
 
 If you regress just nuisance regressors (i.e., rejected components) out of your data,
 then retain the residuals for further analysis, you are doing aggressive denoising.
 
-````{tab} Python
+:::::{tab-set}
+::::{tab-item} Python
 ```python
 # Fit GLM to bad components only
 betas = np.linalg.lstsq(motion_components, arr, rcond=None)[0]
@@ -80,24 +83,26 @@ arr_denoised = arr - pred_arr
 img_denoised = masking.unmask(arr_denoised.T, data['mask'])
 img_denoised.to_filename("denoised.nii.gz")
 ```
-````
-````{tab} FSL
+::::
+::::{tab-item} FSL
 ```bash
 3dcalc --input stuff
 ```
-````
-````{tab} AFNI
+::::
+::::{tab-item} AFNI
 ```bash
 3dcalc --input stuff
 ```
-````
+::::
+:::::
 
 ## Non-Aggressive Denoising
 
 If you include both nuisance regressors and regressors of interest in your regression,
 you are doing nonaggressive denoising.
 
-````{tab} Python
+:::::{tab-set}
+::::{tab-item} Python
 ```python
 # Fit GLM to all components
 betas = np.linalg.lstsq(mixing, arr, rcond=None)[0]
@@ -110,17 +115,18 @@ arr_denoised = arr - pred_arr
 img_denoised = masking.unmask(arr_denoised.T, data['mask'])
 img_denoised.to_filename("denoised.nii.gz")
 ```
-````
-````{tab} FSL
+::::
+::::{tab-item} FSL
 ```bash
 3dcalc --input stuff
 ```
-````
-````{tab} AFNI
+::::
+::::{tab-item} AFNI
 ```bash
 3dcalc --input stuff
 ```
-````
+::::
+:::::
 
 ## Component orthogonalization
 
@@ -130,7 +136,8 @@ If you want to ensure that variance shared between the accepted and rejected com
 you may wish to orthogonalize the rejected components with respect to the accepted components.
 This way, you can regress the rejected components out of the data in the form of, what we call, "pure evil" components.
 
-````{tab} Python
+:::::{tab-set}
+::::{tab-item} Python
 ```python
 good_idx = np.setdiff1d(np.arange(mixing.shape[1]), den_idx)
 
@@ -146,21 +153,23 @@ orth_motion_components = bad_mixing - pred_bad_mixing
 # Replace the old component time series in the mixing matrix with the new ones
 mixing[:, den_idx] = orth_motion_components
 ```
-````
-````{tab} FSL
+::::
+::::{tab-item} FSL
 ```bash
 3dcalc --input stuff
 ```
-````
-````{tab} AFNI
+::::
+::::{tab-item} AFNI
 ```bash
 3dcalc --input stuff
 ```
-````
+::::
+:::::
 
 Once you have these "pure evil" components, you can perform aggressive denoising on the data.
 
-````{tab} Python
+:::::{tab-set}
+::::{tab-item} Python
 ```python
 # Fit GLM to bad components only
 betas = np.linalg.lstsq(orth_motion_components, arr, rcond=None)[0]
@@ -173,14 +182,15 @@ arr_denoised = arr - pred_arr
 img_denoised = masking.unmask(arr_denoised.T, data['mask'])
 img_denoised.to_filename("denoised.nii.gz")
 ```
-````
-````{tab} FSL
+::::
+::::{tab-item} FSL
 ```bash
 3dcalc --input stuff
 ```
-````
-````{tab} AFNI
+::::
+::::{tab-item} AFNI
 ```bash
 3dcalc --input stuff
 ```
-````
+::::
+:::::