Initial commit

.github/workflows/sphinx.yml

@@ -0,0 +1,170 @@
+# Deploy Sphinx.  This could be shorter, but we also do some extra
+# stuff.
+#
+# License: CC-0.  This is the canonical location of this file, which
+# you may want to link to anyway:
+#   https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml
+#  https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/main/.github/workflows/sphinx.yml
+
+
+name: sphinx
+on: [push, pull_request]
+
+env:
+  DEFAULT_BRANCH: "main"
+  # If these SPHINXOPTS are enabled, then be strict about the
+  # builds and fail on any warnings.
+  #SPHINXOPTS: "-W --keep-going -T"
+  GENERATE_PDF: true          # to enable, must be 'true' lowercase
+  GENERATE_SINGLEHTML: true   # to enable, must be 'true' lowercase
+  PDF_FILENAME: lesson.pdf
+  MULTIBRANCH: true    # to enable, must be 'true' lowercase
+
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      # https://github.com/marketplace/actions/checkout
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      # https://github.com/marketplace/actions/setup-python
+      # ^-- This gives info on matrix testing.
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
+      # ^-- This gives info on installing dependencies with pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+        # Debug
+      - name: Debugging information
+        env:
+          ref: ${{github.ref}}
+          event_name: ${{github.event_name}}
+          head_ref: ${{github.head_ref}}
+          base_ref: ${{github.base_ref}}
+        run: |
+          echo "github.ref: ${ref}"
+          echo "github.event_name: ${event_name}"
+          echo "github.head_ref: ${head_ref}"
+          echo "github.base_ref: ${base_ref}"
+          echo "GENERATE_PDF: ${GENERATE_PDF}"
+          echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}"
+          set -x
+          git rev-parse --abbrev-ref HEAD
+          git branch
+          git branch -a
+          git remote -v
+          python -V
+          pip list --not-required
+          pip list
+
+
+      # Build
+      - uses: ammaraskar/sphinx-problem-matcher@master
+      - name: Build Sphinx docs (dirhtml)
+        # SPHINXOPTS used via environment variables
+        run: |
+          make dirhtml
+          # This fixes broken copy button icons, as explained in
+          #   https://github.com/coderefinery/sphinx-lesson/issues/50
+          #   https://github.com/executablebooks/sphinx-copybutton/issues/110
+          # This can be removed once these PRs are accepted (but the
+          # fixes also need to propagate to other themes):
+          #   https://github.com/sphinx-doc/sphinx/pull/8524
+          #   https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
+          sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
+
+      # singlehtml
+      - name: Generate singlehtml
+        if: ${{ env.GENERATE_SINGLEHTML == 'true' }}
+        run: |
+          make singlehtml
+          mv _build/singlehtml/ _build/dirhtml/singlehtml/
+
+      # PDF if requested
+      - name: Generate PDF
+        if: ${{ env.GENERATE_PDF == 'true' }}
+        run: |
+          pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
+          make pyppeteer
+          mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME}
+
+      # Stage all deployed assets in _gh-pages/ for simplicity, and to
+      # prepare to do a multi-branch deployment.
+      - name: Copy deployment data to _gh-pages/
+        if: ${{ github.event_name == 'push' }}
+        run:
+          rsync -a _build/dirhtml/ _gh-pages/
+
+      # Use gh-pages-multibranch to multiplex different branches into
+      # one deployment. See
+      # https://github.com/coderefinery/gh-pages-multibranch
+      - name: gh-pages multibranch
+        uses: coderefinery/gh-pages-multibranch@main
+        if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }}
+        with:
+          directory: _gh-pages/
+          default_branch: ${{ env.DEFAULT_BRANCH }}
+          publish_branch: gh-pages
+
+      # Add the .nojekyll file
+      - name: nojekyll
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          touch _gh-pages/.nojekyll
+
+      # Save artifact for the next step.
+      - uses: actions/upload-artifact@v4
+        if: ${{ github.event_name == 'push' }}
+        with:
+          name: gh-pages-build
+          path: _gh-pages/
+
+  # Deploy in a separate job so that write permissions are restricted
+  # to the minimum steps.
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: build
+    # This if can't use the env context - find better way later.
+    if: ${{ github.event_name == 'push' }}
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
+        with:
+          name: gh-pages-build
+          path: _gh-pages/
+
+      # As of 2023, we could publish to pages via a Deployment.  This
+      # isn't done yet to give it time to stabilize (out of beta), and
+      # also having a gh-pages branch to check out is rather
+      # convenient.
+
+      # Deploy
+      # https://github.com/peaceiris/actions-gh-pages
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _gh-pages/
+          force_orphan: true

.gitignore

@@ -0,0 +1,5 @@
+/_build
+.ipynb_checkpoints
+/venv*
+.jupyter_cache
+jupyter_execute

Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = content
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Live reload site documents for local development
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

content/conf.py

@@ -0,0 +1,103 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "LESSON NAME"
+copyright = "2020, The contributors"
+author = "The contributors"
+github_user = "coderefinery"
+github_repo_name = ""  # auto-detected from dirname if blank
+github_version = "main"
+conf_py_path = "/content/"  # with leading and trailing slash
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    # githubpages just adds a .nojekyll file
+    "sphinx.ext.githubpages",
+    "sphinx_lesson",
+    # remove once sphinx_rtd_theme updated for contrast and accessibility:
+    "sphinx_rtd_theme_ext_color_contrast",
+]
+
+# Settings for myst_nb:
+# https://myst-nb.readthedocs.io/en/latest/use/execute.html#triggering-notebook-execution
+# jupyter_execute_notebooks = "off"
+# jupyter_execute_notebooks = "auto"   # *only* execute if at least one output is missing.
+# jupyter_execute_notebooks = "force"
+jupyter_execute_notebooks = "cache"
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "README*",
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "jupyter_execute",
+    "*venv*",
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+
+# HTML context:
+from os.path import basename, dirname, realpath
+
+html_context = {
+    "display_github": True,
+    "github_user": github_user,
+    # Auto-detect directory name.  This can break, but
+    # useful as a default.
+    "github_repo": github_repo_name or basename(dirname(realpath(__file__))),
+    "github_version": github_version,
+    "conf_py_path": conf_py_path,
+}
+
+# Intersphinx mapping.  For example, with this you can use
+# :py:mod:`multiprocessing` to link straight to the Python docs of that module.
+# List all available references:
+#   python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+# extensions.append('sphinx.ext.intersphinx')
+# intersphinx_mapping = {
+#    #'python': ('https://docs.python.org/3', None),
+#    #'sphinx': ('https://www.sphinx-doc.org/', None),
+#    #'numpy': ('https://numpy.org/doc/stable/', None),
+#    #'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+#    #'pandas': ('https://pandas.pydata.org/docs/', None),
+#    #'matplotlib': ('https://matplotlib.org/', None),
+#    'seaborn': ('https://seaborn.pydata.org/', None),
+# }

content/guide.rst

@@ -0,0 +1,37 @@
+Instructor's guide
+==================
+
+Why we teach this lesson
+------------------------
+
+
+
+Intended learning outcomes
+--------------------------
+
+
+
+Timing
+------
+
+
+
+Preparing exercises
+-------------------
+
+e.g. what to do the day before to set up common repositories.
+
+
+
+Other practical aspects
+-----------------------
+
+
+
+Interesting questions you might get
+-----------------------------------
+
+
+
+Typical pitfalls
+----------------