doc updates

Author: cgcgcg

Diff for: .flake8

@@ -2,6 +2,8 @@
 extend-ignore =
     # E402: module level import not at top of file
     E402,
+    # E741 ambiguous variable name
+    E741,
     # H301: one import per line
     H301,
     # H306: imports not in alphabetical order

Diff for: .github/workflows/build.yml

@@ -44,17 +44,17 @@ jobs:
     steps:
     - name: Check out repo
       if: always()
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Pull ccache cache
       if: always()
       id: ccache-restore
-      uses: actions/cache/restore@v3
+      uses: actions/cache/restore@v4
       with:
         path: /home/runner/.cache/ccache
         key: ccache-${{ env.BUILD_IDENTIFIER }}
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       if: always()
       with:
         python-version: ${{ matrix.py-version }}
@@ -89,7 +89,7 @@ jobs:
 
     - name: Push ccache cache
       if: always()
-      uses: actions/cache/save@v3
+      uses: actions/cache/save@v4
       with:
         path: /home/runner/.cache/ccache
         key: ccache-${{ env.BUILD_IDENTIFIER }}
@@ -115,7 +115,7 @@ jobs:
         mv cython-lint.xml cython-lint-${{ env.BUILD_IDENTIFIER }}.xml
 
     - name: Archive results
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: always()
       with:
         name: Results (${{ env.BUILD_PRETTY_IDENTIFIER }})
@@ -154,20 +154,20 @@ jobs:
 
     steps:
     - name: Check out repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Pull ccache cache
       if: always()
       id: ccache-restore
-      uses: actions/cache/restore@v3
+      uses: actions/cache/restore@v4
       with:
         path: /Users/runner/Library/Caches/ccache
         key: ccache-${{ runner.os }}-${{ matrix.py-version }}
 
     - name: Setup GNU Fortran
       uses: fortran-lang/setup-fortran@v1
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.py-version }}
 
@@ -203,7 +203,7 @@ jobs:
 
     - name: Push ccache cache
       if: always()
-      uses: actions/cache/save@v3
+      uses: actions/cache/save@v4
       with:
         path: /Users/runner/Library/Caches/ccache
         key: ccache-${{ runner.os }}-${{ matrix.py-version }}
@@ -229,7 +229,7 @@ jobs:
         mv cython-lint.xml cython-lint-${{ runner.os }}-${{ matrix.py-version }}.xml
 
     - name: Archive results
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: always()
       with:
         name: Results ${{ github.job }}

Diff for: .github/workflows/container.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
     - name: Check out
       if: always()
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 

Diff for: .github/workflows/documentation-ci.yml

@@ -0,0 +1,70 @@
+name: Documentation CI
+
+on:
+  pull_request:
+    branches: [ "master" ]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+
+  linux:
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    env:
+      MPIEXEC_FLAGS: "--allow-run-as-root --oversubscribe"
+      PYNUCLEUS_BUILD_PARALLELISM: 2
+
+    steps:
+    - name: Check out repo
+      uses: actions/checkout@v4
+
+    - name: Pull ccache cache
+      id: ccache-restore
+      uses: actions/cache/restore@v4
+      with:
+        path: /home/runner/.cache/ccache
+        key: ccache
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install Ubuntu packages
+      run: |
+        sudo apt-get update
+        sudo apt-get install mpi-default-bin mpi-default-dev libmetis-dev libparmetis-dev libsuitesparse-dev ccache
+
+    - name: Install Python dependencies
+      run: make prereq && make prereq-extra && python -m pip install wheel
+
+    - name: Install
+      run: make dev
+
+    - name: Remove ccache cache
+      if: ${{ steps.ccache-restore.outputs.cache-hit }}
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        gh extension install actions/gh-actions-cache
+        gh actions-cache delete ccache --confirm
+      continue-on-error: true
+
+    - name: Push ccache cache
+      uses: actions/cache/save@v4
+      with:
+        path: /home/runner/.cache/ccache
+        key: ccache
+
+    - name: Build documentation
+      run: |
+        make docs
+        cat docs/example1_stepMesh.py
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: 'docs/build'

Diff for: .github/workflows/documentation.yml

@@ -1,4 +1,3 @@
-
 name: Documentation
 
 on:
@@ -26,16 +25,16 @@ jobs:
 
     steps:
     - name: Check out repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Pull ccache cache
       id: ccache-restore
-      uses: actions/cache/restore@v3
+      uses: actions/cache/restore@v4
       with:
         path: /home/runner/.cache/ccache
         key: ccache
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: '3.11'
 
@@ -61,7 +60,7 @@ jobs:
       continue-on-error: true
 
     - name: Push ccache cache
-      uses: actions/cache/save@v3
+      uses: actions/cache/save@v4
       with:
         path: /home/runner/.cache/ccache
         key: ccache
@@ -72,13 +71,13 @@ jobs:
         cat docs/example1_stepMesh.py
 
     - name: Setup Pages
-      uses: actions/configure-pages@v3
+      uses: actions/configure-pages@v4
 
     - name: Upload artifact
-      uses: actions/upload-pages-artifact@v1
+      uses: actions/upload-pages-artifact@v4
       with:
         path: 'docs/build'
 
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v2
+      uses: actions/deploy-pages@v4

Diff for: Dockerfile

@@ -25,6 +25,7 @@ RUN sed -i 's/Components: main/Components: main contrib non-free/' /etc/apt/sour
         libmetis-dev libparmetis-dev \
         texlive texlive-extra-utils texlive-latex-extra ttf-staypuft dvipng cm-super \
         jupyter-notebook \
+        emacs-nox vim \
   --no-install-recommends \
   && rm -rf /var/lib/apt/lists/*
 
@@ -36,12 +37,10 @@ WORKDIR /pynucleus
 RUN make prereq PIP_FLAGS=--no-cache-dir && \
     make prereq-extra PIP_FLAGS=--no-cache-dir && \
     make install && \
+    make docs && \
     python -m pip install --no-cache-dir ipykernel && \
     rm -rf build packageTools/build base/build metisCy/build fem/build multilevelSolver/build nl/build
 
-RUN echo "alias ls='ls --color=auto -FN'" >> /root/.bashrc \
-    && echo 'set completion-ignore-case On' >> /root/.inputrc
-
 # allow running MPI as root in the container
 # bind MPI ranks to hwthreads
 ENV OMPI_MCA_hwloc_base_binding_policy=hwthread \
@@ -53,4 +52,6 @@ RUN python -m ipykernel install --name=PyNucleus
 
 COPY README.container.rst /README.container.rst
 # hadolint ignore=SC2016
-RUN echo '[ ! -z "$TERM" -a -r /README.container.rst ] && cat /README.container.rst' >> /etc/bash.bashrc
+RUN echo '[ ! -z "$TERM" -a -r /README.container.rst ] && echo -e "\e[32m" && cat /README.container.rst && echo -e "\e[0m"' >> /etc/bash.bashrc
+
+WORKDIR /root

Diff for: Makefile

@@ -115,8 +115,8 @@ clean_package :
 
 .PHONY: docs
 docs :
-	cd docs && make
 	$(PYTHON) -m sphinx -b html docs docs/build
+	find docs/build/_downloads -name "*.ipynb" | xargs -I {} cp {} examples
 
 clean_docs :
 	cd docs; rm -rf build
@@ -169,7 +169,7 @@ prereq:
 	$(PYTHON) -m pip install $(PIP_FLAGS) $(PIP_INSTALL_FLAGS) scikit-sparse
 
 prereq-extra:
-	$(PYTHON) -m pip install $(PIP_FLAGS) pytest pytest-html pytest-xdist Sphinx sphinxcontrib-programoutput flake8 flake8-junit-report cython-lint
+	$(PYTHON) -m pip install $(PIP_FLAGS) pytest pytest-html pytest-xdist Sphinx sphinxcontrib-programoutput sphinx-gallery sphinx-rtd-theme flake8 flake8-junit-report cython-lint
 
 flake8:
 	$(PYTHON) -m flake8 --output-file=flake8.txt --exit-zero drivers examples packageTools base metisCy fem multilevelSolver nl tests

Diff for: README.container.rst

@@ -1,6 +1,12 @@
 
 This is a container image for PyNucleus.
 
-The drivers and examples for PyNucleus can be found in /pynucleus/drivers and /pynucleus/examples
+The directory from which the container was launched on the host system is mapped to /root.
+PyNucleus is installed at /pynucleus.
+A copy of the drivers and examples for PyNucleus can be found in /root/drivers and /root/examples.
+The Jupyter notebook interface is available at https://localhost:8889 on the host.
+A quick way to check that everything works is to run
 
-The directory from which the container was launched on the host system is mapped to /user
+  /root/drivers/runFractional.py
+
+This should print some information about the solution of a fractional Laplacian problem and show several plots.

Diff for: README.rst

@@ -73,55 +73,62 @@ and open ``docs/build/index.html`` in your browser.
 Possible ways to install and use PyNucleus
 ==================================
 
+There are several ways to install and run PyNucleus:
+
 * container image
 * Spack installation
 * manual installation
 
+The easiest way to get up and running is probably the container image.
+
 
 Container image
 ----------------
 
 The simplest way to use PyNucleus is to pull a container image from the GitHub Container Registry.
 This requires an installation of either
 
-* podman (https://podman.io/) and podman-compose (https://github.com/containers/podman-compose) or
-* Docker (https://www.docker.com/) and Docker Compose (https://docs.docker.com/compose/install/).
+* `podman <https://podman.io/>`_ and `podman-compose <https://github.com/containers/podman-compose?tab=readme-ov-file#installation>`_ or
+* `Docker <https://www.docker.com/>`_ and `Docker Compose <https://docs.docker.com/compose/install/>`_.
 
 For many Linux distributions these can be installed from the package repositories.
-In what follows we will assume that we are using podman.
+In what follows we will assume that we are using `podman`.
 All commands for Docker should be identical up to the substitution of `podman` with `docker`.
 
-For example, on Ubuntu podman can be installed with
+For example, on Ubuntu podman and podman-compose can be installed with
 
 .. code-block:: shell
 
    sudo apt-get install podman podman-compose
 
-Instructions for other platforms can be found here: https://podman.io/docs/installation
+Instructions for other platforms can be found `here <https://podman.io/docs/installation>`_.
+
+Once podman is installed, we download a copy of `compose.yaml <https://github.com/sandialabs/PyNucleus/blob/master/compose.yaml>`_ and save it to an empty directory.
+
+.. warning::
+   Please do not copy this file to your home directory and launch the container from there.
+   The container keeps its state in the directory where it is launched from.
 
-Once podman is installed, we can download a copy of https://github.com/sandialabs/PyNucleus/blob/master/compose.yaml and save it to an empty directory.
 In that directory we then run
 
 .. code-block:: shell
 
-   podman compose run pynucleus
+   podman-compose run pynucleus
+
+podman will download a container image for PyNucleus and then launch a shell in the container.
+
+.. note::
+   The download of the image will only happen once, but it could be several GB in size.
 
-This launches a shell on the container with PyNucleus.
 A simple way to test if things work is to run
 
 .. code-block:: shell
 
    drivers/runFractional.py
 
-This should print some information about the solution of a fractional Laplacian problem and open up several plots.
-
-For development using PyNucleus it can be useful to launch a Jupyter notebook server:
-
-.. code-block:: shell
-
-   podman compose up pynucleus-jupyter
+This should print some information about the solution of a fractional Laplacian problem and show several plots.
 
-and then open the Jupyter notebook interface at https://localhost:8889
+For development using PyNucleus there is the Jupyter notebook interface that is available while the container is running at https://localhost:8889 on the host system.
 
 
 Spack install