diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8587102..24e6c5c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -100,3 +100,19 @@ jobs: - name: Build static site run: pixi run build + + myst_build: + name: Build and execute static site with myst + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup environment + run: pip install -r requirements.txt + - name: Build site with execution + run: | + myst build --execute 2>&1 |tee /tmp/mystbuild.log + if grep -q "Traceback .most recent call last." /tmp/mystbuild.log; then + exit 1; + else + exit 0; + fi diff --git a/README.md b/README.md index 3898d59..9c372a5 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,40 @@ covering some core features: pip install -r requirements.txt jupyter lab ``` +## Build the site + +There are currently two distinct technology stacks that support the +`executable-tutorials` paradigm: a legacy sphinx-based static-site generation +engine, and the newer [myst][myst-org] project. +The `executable-tutorials` repo contains information about both development +patterns, and endeavors to serve as a transition guide between technology +stacks. + +By default, the necessary tooling for both technology stacks is installed with +`pip install -r requirements.txt` + +### Build with sphinx + +```bash +make html +``` + +The static site can then be viewed by simply opening the index in any browser, +for example:: + +```bash +firefox _build/html/index.html +``` + +### Build with `myst` + +```bash +myst start --execute +``` + +This will execute the notebooks, build the site, and set up a server for rendering +the site. +The rendered page can be viewed by opening `localhost:3000` in a browser. ## Make Your Own diff --git a/myst.yml b/myst.yml new file mode 100644 index 0000000..76a7197 --- /dev/null +++ b/myst.yml @@ -0,0 +1,27 @@ +# See docs at: https://mystmd.org/guide/frontmatter +version: 1 +project: + id: 9db2473e-461d-4266-86fa-a2a0ea3eb2c9 + title: executable-tutorials + description: Executable tutorials for Scientific Python + keywords: [] + authors: [Scientific Python Developers] + github: https://github.com/scientific-python/executable-tutorials + # To autogenerate a Table of Contents, run "myst init --write-toc" + toc: + # Auto-generated by `myst init --write-toc` + - file: index.md + - title: Tutorials + children: + - file: tutorials/executable/basics.md + - file: tutorials/matplotlib/interactive_mpl.md + - file: tutorials/matplotlib/static_mpl.md + - file: tutorials/static/static.md + - file: contributing.md + - file: maintainers.md + +site: + template: book-theme + # options: + # favicon: favicon.ico + # logo: site_logo.png diff --git a/requirements.txt b/requirements.txt index 6c58584..39db3df 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,3 +12,6 @@ nbval pytest-custom_exit_code jupytext jupyterlab-myst +# For myst stack +mystmd +jupyter