doc updates

.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

.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 }}

.github/workflows/container.yml

@@ -3,6 +3,8 @@ name: Container
 on:
   push:
     branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
   workflow_dispatch:
 
 env:
@@ -21,14 +23,15 @@ jobs:
     steps:
     - name: Check out
       if: always()
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
-    - uses: hadolint/[email protected]
-      with:
-        dockerfile: Dockerfile
-        ignore: 'DL3008,DL3013'
+    # - uses: hadolint/[email protected]
+    #   with:
+    #     dockerfile: Dockerfile
+    #     ignore: 'DL3008,DL3013'
+    #     verbose: true
 
     - name: Build Image
       id: build_image
@@ -41,9 +44,10 @@ jobs:
 
     - name: Run tests
       run: |
-        podman run -e MPIEXEC_FLAGS="--allow-run-as-root --oversubscribe" --rm ${{ steps.build_image.outputs.image }}:${{ github.sha }} python3 -m pytest --junit-xml=test-results.xml tests/
+        podman run -e MPIEXEC_FLAGS="--allow-run-as-root --oversubscribe" --workdir /pynucleus --rm ${{ steps.build_image.outputs.image }}:${{ github.sha }} python3 -m pytest --junit-xml=test-results.xml tests/
 
     - name: Push To GHCR
+      if: github.event_name == 'push'
       uses: redhat-actions/push-to-registry@v2
       id: push
       with:
@@ -56,5 +60,6 @@ jobs:
           --disable-content-trust
 
     - name: Echo outputs
+      if: github.event_name == 'push'
       run: |
         echo "${{ toJSON(steps.push.outputs) }}"

.github/workflows/documentation-ci.yml

@@ -0,0 +1,69 @@
+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
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        path: 'docs/build'

.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,24 +60,23 @@ 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
 
     - name: Build documentation
       run: |
         make docs
-        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@v3
       with:
         path: 'docs/build'
 
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v2
+      uses: actions/deploy-pages@v4

Dockerfile

@@ -6,12 +6,13 @@
 FROM debian:testing
 LABEL maintainer Christian Glusa
 
-ENV LANG C.UTF-8
+ENV LANG en_US.UTF-8
 
 # install packages needed for build
 RUN sed -i 's/Components: main/Components: main contrib non-free/' /etc/apt/sources.list.d/debian.sources \
   && apt-get update && \
   DEBIAN_FRONTEND=noninteractive apt-get install -y \
+        locales \
         autoconf automake gcc g++ make gfortran wget zlib1g-dev libffi-dev \
         tk-dev \
         libssl-dev ca-certificates cmake \
@@ -25,32 +26,37 @@ 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/*
-
-COPY . /pynucleus
-ENV VIRTUAL_ENV=/pynucleus/venv
-RUN python3 -m venv $VIRTUAL_ENV
-ENV PATH="$VIRTUAL_ENV/bin:$PATH"
-WORKDIR /pynucleus
-RUN make prereq PIP_FLAGS=--no-cache-dir && \
-    make prereq-extra PIP_FLAGS=--no-cache-dir && \
-    make install && \
-    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
+  && rm -rf /var/lib/apt/lists/* \
+  && sed -i -e "s/# $LANG.*/$LANG UTF-8/" /etc/locale.gen \
+  && dpkg-reconfigure --frontend=noninteractive locales \
+  && update-locale LANG=$LANG
 
 # allow running MPI as root in the container
 # bind MPI ranks to hwthreads
-ENV OMPI_MCA_hwloc_base_binding_policy=hwthread \
+ENV LANG=en_US.UTF-8 \
+    LANGUAGE=en_US:en \
+    LC_ALL=en_US.UTF-8 \
+    VIRTUAL_ENV=/pynucleus/venv \
+    PATH="/pynucleus/venv/bin:$PATH" \
+    OMPI_MCA_hwloc_base_binding_policy=hwthread \
     MPIEXEC_FLAGS=--allow-run-as-root \
     OMPI_ALLOW_RUN_AS_ROOT=1 \
     OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1
 
-RUN python -m ipykernel install --name=PyNucleus
+COPY . /pynucleus
+
+WORKDIR /pynucleus
+
+RUN python3 -m venv $VIRTUAL_ENV && \
+    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 && \
+    python -m ipykernel install --name=PyNucleus && \
+    echo '[ ! -z "$TERM" -a -r /pynucleus/README.container.rst ] && printf "\e[32m" && cat /pyncleus/README.container.rst && printf "\e[0m"' >> /etc/bash.bashrc
 
-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
+WORKDIR /root

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

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.