DOC: move examples into repository (#169)

Move the examples as notebooks into the repository. The documentation
uses the pre-computed notebook outputs, and so doesn't need to compute
the costly examples every time.

The examples have also been updated slightly, to reflect the changing
best practices.

Closes: #168

.github/workflows/test.yml

@@ -9,12 +9,14 @@ on:
     - main
 
 jobs:
+
   style:
     name: Style
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
     - run: pipx run flake8 glass
+
   tests:
     name: Tests
     runs-on: ubuntu-latest
@@ -23,20 +25,44 @@ jobs:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
     - uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - run: pip install -c .github/test-constraints.txt '.[test]'
     - run: pytest --pyargs glass
+
   build:
     name: Build
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
     - run: pipx run build
+
   docs:
     name: Docs
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - run: |
+        sudo apt-get update
+        sudo apt-get install pandoc
     - run: pipx run --spec '.[docs]' sphinx-build -W -b html docs _build/html
+
+  examples:
+    name: Examples
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+        cache: pip
+    - run: pipx run --spec '.[examples]' jupyter execute examples/**/*.ipynb

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pycqa/flake8
-  rev: 4.0.1
+  rev: 7.1.1
   hooks:
   - id: flake8
     additional_dependencies:

docs/conf.py

@@ -4,22 +4,16 @@
 # 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 -----------------------------------------------------
 
+from importlib import metadata
+
 project = 'GLASS'
-copyright = '2022, Nicolas Tessore'
+copyright = '2022-2024 Nicolas Tessore'
 author = 'Nicolas Tessore'
+version = metadata.version("glass")
+release = version
 
 
 # -- General configuration ---------------------------------------------------
@@ -32,6 +26,7 @@
     'sphinx.ext.intersphinx',
     'sphinxcontrib.katex',
     'matplotlib.sphinxext.plot_directive',
+    'nbsphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -56,28 +51,8 @@
 html_static_path = ['_static']
 
 html_logo = '_static/logo.png'
-
 html_favicon = '_static/favicon.ico'
-
-html_theme_options = {
-    'footer_icons': [
-        {
-            'name': 'Documentation',
-            'url': 'https://glass.readthedocs.io',
-            'html': '<svg xmlns="http://www.w3.org/2000/svg" stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 576 512"><!--! Font Awesome Pro 6.3.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path d="M575.8 255.5c0 18-15 32.1-32 32.1h-32l.7 160.2c0 2.7-.2 5.4-.5 8.1V472c0 22.1-17.9 40-40 40H456c-1.1 0-2.2 0-3.3-.1c-1.4 .1-2.8 .1-4.2 .1H416 392c-22.1 0-40-17.9-40-40V448 384c0-17.7-14.3-32-32-32H256c-17.7 0-32 14.3-32 32v64 24c0 22.1-17.9 40-40 40H160 128.1c-1.5 0-3-.1-4.5-.2c-1.2 .1-2.4 .2-3.6 .2H104c-22.1 0-40-17.9-40-40V360c0-.9 0-1.9 .1-2.8V287.6H32c-18 0-32-14-32-32.1c0-9 3-17 10-24L266.4 8c7-7 15-8 22-8s15 2 21 7L564.8 231.5c8 7 12 15 11 24z"/></svg>',
-            'class': '',
-        },
-        {
-            'name': 'GitHub',
-            'url': 'https://github.com/glass-dev/glass',
-            'html': '<svg xmlns="http://www.w3.org/2000/svg" stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 496 512"><!--! Font Awesome Pro 6.3.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>',
-            'class': '',
-        },
-    ],
-}
-
-html_css_files = [
-]
+html_css_files = []
 
 
 # -- Intersphinx -------------------------------------------------------------
@@ -87,7 +62,6 @@
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
-    'examples': ('https://glass.readthedocs.io/projects/examples/latest/', None),
 }
 
 

docs/examples

@@ -0,0 +1 @@
+../examples

docs/examples.rst

@@ -0,0 +1,47 @@
+
+Examples
+========
+
+These examples show how GLASS can be used in practice.  They are often a good
+starting point for more complicated and realistic simulations.
+
+The examples currently require `CAMB`__ to produce angular matter power spectra
+and for the cosmological background.  Make sure you have CAMB installed:
+
+.. code-block:: console
+
+    $ python -c 'import camb'  # should not give an error
+
+If you want to compute the angular matter power spectra in the examples, you
+need the `glass.ext.camb` package:
+
+.. code-block:: console
+
+    $ pip install glass.ext.camb
+
+__ https://camb.readthedocs.io/
+
+
+Basic examples
+--------------
+
+To get started, these examples focus on simulating one thing at a time.
+
+.. nbgallery::
+
+   examples/1-basic/shells.ipynb
+   examples/1-basic/matter.ipynb
+   examples/1-basic/density.ipynb
+   examples/1-basic/lensing.ipynb
+   examples/1-basic/photoz.ipynb
+
+
+Advanced examples
+-----------------
+
+More advanced examples doing multiple things at the same time.
+
+.. nbgallery::
+
+   examples/2-advanced/cosmic_shear.ipynb
+   examples/2-advanced/stage_4_galaxies.ipynb

docs/index.rst

@@ -21,7 +21,7 @@ Table of Contents
    :maxdepth: 2
 
    manual/index
-   Examples <https://glass.readthedocs.io/projects/examples/>
+   examples
    user/index
    reference/index