Use EVITA based template

.github/workflows/sphinx.yml

@@ -30,25 +30,26 @@ jobs:
 
     steps:
       # https://github.com/marketplace/actions/checkout
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
+          persist-credentials: false
           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
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.11'
+          python-version: '3.13'
           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
+          pip install --group notebook .
 
         # Debug
       - name: Debugging information
@@ -80,14 +81,6 @@ jobs:
         # 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
@@ -100,7 +93,6 @@ jobs:
       - name: Generate PDF
         if: ${{ env.GENERATE_PDF == 'true' }}
         run: |
-          #pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
           pip install sphinx_pyppeteer_builder
           make pyppeteer
           mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME}

.gitignore

@@ -3,3 +3,4 @@
 /venv*
 .jupyter_cache
 jupyter_execute
+uv.lock

CITATION.cff

@@ -0,0 +1,2 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!

LICENSE.code

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, ENCCS and individual contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -12,13 +12,16 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile lock
 
 # 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)
 
+lock:
+	uv export -o pylock.toml
+
 # Live reload site documents for local development
 livehtml:
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

content/conf.py

@@ -10,17 +10,17 @@
 # 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"
+# FIXME: choose title
+project = "Your lesson name"
+# FIXME: insert correct author
 author = "The contributors"
-github_user = "coderefinery"
+copyright = f"2025, ENCCS, {author}"
+
+# FIXME: github organization / user that the repository belongs to
+github_user = "ENCCS"
 github_repo_name = ""  # auto-detected from dirname if blank
 github_version = "main"
 conf_py_path = "/content/"  # with leading and trailing slash
@@ -34,21 +34,26 @@
     # 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",
+    "sphinx_evita",
+    "sphinxcontrib.bibtex",
+    "myst_nb",
+    "sphinx.ext.todo",
+    "sphinx.ext.intersphinx",
 ]
 
+# FIXME: add bibtex files for references if any
+bibtex_bibfiles = []
+
 # 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"
+# nb_execution_mode = "off"
+# nb_execution_mode = "auto"   # *only* execute if at least one output is missing.
+# nb_execution_mode = "force"
 nb_execution_mode = "cache"
 
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
-myst_enable_extensions = [
-    "colon_fence",
-]
+myst_enable_extensions = ["colon_fence", "attrs_inline", "substitution"]
+myst_substitutions = {"author": author}
 
 # Settings for sphinx-copybutton
 copybutton_exclude = ".linenos, .gp"
@@ -68,44 +73,71 @@
     "*venv*",
 ]
 
-
 # -- Options for HTML output -------------------------------------------------
+from pathlib import Path
+
+
+HERE = Path(__file__).parent
+detected_repo_name = HERE.parent.name
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_title = project
+html_theme = "furo"
 
 # 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_static_path = ["_static"]
+# html_css_files = ["overrides.css"]
+html_favicon = str((HERE / "_static" / "favicon.ico").resolve())
+html_theme_options = {
+    "light_logo": "ENCCS_logo_light.png",
+    "dark_logo": "ENCCS_logo_dark.png",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": f"https://github.com/ENCCS/{github_repo_name or detected_repo_name}",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+}
 
 
 # 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_repo": github_repo_name or detected_repo_name,
     "github_version": github_version,
     "conf_py_path": conf_py_path,
 }
 
+# FIXME: modify intersphinx mapping to link to external content
+
 # 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),
-# }
+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),
+    # "evita": ("https://sphinx-evita.readthedocs.io/en/latest", None),
+    # "instruct": ("https://enccs.github.io/instructor-training/", None),
+    # "lesson": ("https://coderefinery.github.io/sphinx-lesson/", None),
+    # "myst": ("https://myst-parser.readthedocs.io/en/latest/", None),
+}

content/index.md

@@ -3,8 +3,11 @@
 Intro
 
 :::{prereq}
-prerequisites
-:::
+
+- FIXME
+- ...
+- ...
+  :::
 
 ```{csv-table}
 :delim: ;
@@ -28,12 +31,87 @@ quick-reference
 guide
 ```
 
-(learner-personas)=
+## Learning outcomes
+
+FIXME
+
+This material is for ...
 
-## Who is the course for?
+By the end of this module, learners should:
 
-## About the course
+- ...
+- ...
 
 ## See also
 
-## Credits
+:::{admonition} Credit
+:class: warning
+
+FIXME
+
+Don't forget to check out additional course materials from ...
+
+:::
+
+::::{admonition} License
+:class: attention
+
+:::{admonition} CC BY-SA for media and pedagogical material
+:class: attention dropdown
+
+Copyright © 2025 XXX. This material is released by XXX under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
+
+**Canonical URL**: <https://creativecommons.org/licenses/by-sa/4.0/>
+
+[See the legal code](https://creativecommons.org/licenses/by-sa/4.0/legalcode.en)
+
+## You are free to
+
+1. **Share** — copy and redistribute the material in any medium or format for any purpose, even commercially.
+2. **Adapt** — remix, transform, and build upon the material for any purpose, even commercially.
+3. The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+## Under the following terms
+
+1. **Attribution** — You must give [appropriate credit](https://creativecommons.org/licenses/by-sa/4.0/#ref-appropriate-credit) , provide a link to the license, and [indicate if changes were made](https://creativecommons.org/licenses/by-sa/4.0/#ref-indicate-changes) . You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+2. **ShareAlike** — If you remix, transform, or build upon the material, you must distribute your contributions under the [same license](https://creativecommons.org/licenses/by-sa/4.0/#ref-same-license) as the original.
+3. **No additional restrictions** — You may not apply legal terms or [technological measures](https://creativecommons.org/licenses/by-sa/4.0/#ref-technological-measures) that legally restrict others from doing anything the license permits.
+
+## Notices
+
+You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable [exception or limitation](https://creativecommons.org/licenses/by/4.0/deed.en#ref-exception-or-limitation) .
+
+No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as [publicity, privacy, or moral rights](https://creativecommons.org/licenses/by/4.0/deed.en#ref-publicity-privacy-or-moral-rights) may limit how you use the material.
+
+This deed highlights only some of the key features and terms of the actual license. It is not a license and has no legal value. You should carefully review all of the terms and conditions of the actual license before using the licensed material.
+
+:::
+
+:::{admonition} MIT for source code and code snippets
+:class: attention dropdown
+
+MIT License
+
+Copyright (c) 2025, ENCCS project, {{ author }}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+:::
+
+::::