ENH: switch to the mystmd enginery for rendering

.github/workflows/ci_publish.yml

@@ -0,0 +1,46 @@
+name: Build and Publish HTML and deployed_notebooks
+
+on:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '0 5 * * 1'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # `BASE_URL` determines, relative to the root of the domain, the URL that your site is served from.
+  # E.g., if your site lives at `https://mydomain.org/myproject`, set `BASE_URL=/myproject`.
+  # If, instead, your site lives at the root of the domain, at `https://mydomain.org`, set `BASE_URL=''`.
+  BASE_URL: /${{ github.event.repository.name }}
+
+jobs:
+
+  publish_html:
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    name: Publish HTML
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: python -m pip install --upgrade tox
+
+      - name: Execute notebooks while building HTMLs
+        run: tox -e py312-buildhtml
+
+      - name: Publish
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e  # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_build/html/
+          commit_message: ${{ github.event.head_commit.message }}

.gitignore

@@ -23,6 +23,7 @@ pmip
 tags
 cscope.out
 .ipynb_checkpoints
+.tox
 
 # Compiled source #
 ###################

environment.yml

@@ -10,9 +10,9 @@ dependencies:
   - pandas
   - imageio
   # For building the site
-  - sphinx
-  - myst-nb
-  - sphinx-book-theme
-  - sphinx-copybutton
-  # to load the md files in binder
+  - tox
   - jupytext
+  - pip
+  - pip:
+    - jupyter-book>=2
+    - jupyterlab_myst

myst.yml

@@ -0,0 +1,35 @@
+version: 1
+project:
+  title: Numpy Tutorials
+  # description:
+  # keywords: []
+  authors: Numpy Community
+  github: https://github.com/numpy/numpy-tutorials
+  toc:
+    - file: site/index.md
+
+    - title: Applications
+      children:
+        - file: content/mooreslaw-tutorial.md
+        - file: content/tutorial-deep-learning-on-mnist.md
+        - file: content/tutorial-x-ray-image-processing.md
+        - file: content/tutorial-static_equilibrium.md
+        - file: content/tutorial-plotting-fractals.md
+        - file: content/tutorial-air-quality-analysis.md
+
+    - title: Features
+      children:
+        - file: content/tutorial-svd.md
+        - file: content/save-load-arrays.md
+        - file: content/tutorial-ma.md
+    - title: Contributing
+      file: site/contributing.md
+      children:
+        - file: content/tutorial-style-guide.md
+
+
+site:
+  template: book-theme
+  options:
+    favicon: site/_static/favicon.png
+    logo: site/_static/numpylogo.svg

site/contributing.md

@@ -44,12 +44,6 @@ accept both Jupyter notebooks (`.ipynb`) and MyST-NB notebooks (`.md`).
 If you want to sync your `.ipynb` to your `.md` file follow the [pairing
 tutorial](content/pairing).
 
-```{toctree}
-:hidden:
-
-content/pairing
-```
-
 ## Adding your own tutorials
 
 If you have your own tutorial in the form of a Jupyter notebook (an `.ipynb`
@@ -66,14 +60,7 @@ We will try to respond as quickly as possible with comments, if applicable.
 ### Check out our suggested template
 
 You can use this template to make your content consistent with our existing
-tutorials:
-
-```{toctree}
----
-maxdepth: 1
----
-content/tutorial-style-guide
-```
+tutorials.
 
 ### Upload your content
 

site/index.md

@@ -19,18 +19,6 @@ local copy of the `.ipynb` files, you can either
 [clone this repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository)
 or use the download icon in the upper-right corner of each tutorial.
 
-## Content
-
-```{toctree}
----
-maxdepth: 2
----
-
-features
-applications
-contributing
-```
-
 ### Non-executable articles
 
 ```{admonition} Help improve the tutorials!
@@ -39,14 +27,6 @@ Want to make a valuable contribution to the tutorials? Consider contributing to
 these existing articles to help make them fully executable and reproducible!
 ```
 
-```{toctree}
----
-maxdepth: 2
----
-
-articles
-```
-
 ## Useful links and resources
 
 The following links may be useful:

site/requirements.txt

@@ -1,4 +1 @@
-sphinx
-myst-nb
-sphinx-book-theme
-sphinx-copybutton
+jupyter-book>=2

tox.ini

@@ -11,6 +11,8 @@ description = run tests
 setenv =
     devdeps: PIP_EXTRA_INDEX_URL =  https://pypi.anaconda.org/scientific-python-nightly-wheels/simple
 
+passenv = BASE_URL
+
 deps =
     # We use these files to specify all the dependencies, and below we override
     # versions for specific testing schenarios
@@ -28,7 +30,7 @@ deps =
     devdeps: matplotlib>=0.0.dev0
     devdeps: pandas>=0.0.dev0
 
-allowlist_externals = bash, make
+allowlist_externals = bash
 
 commands =
     # Force numpy reinstall to work around upper version limits in downstream dependencies (e.g. pandas)
@@ -40,7 +42,8 @@ commands =
     !buildhtml: bash -c 'find content -name "*.md" | grep -vf ignore_testing | xargs jupytext --to notebook '
 
     !buildhtml: pytest --nbval-lax --durations=10 content/
-    buildhtml: make -C site/ SPHINXOPTS="-nWT --keep-going" html
+
+    buildhtml: bash -c "jupyter-book build --execute --html -d"
 
 pip_pre =
     predeps: true