Docs changes from #480

.github/workflows/CI.yml

@@ -7,6 +7,7 @@ on:
       - '**'
   schedule:
     - cron: '0 0 * * 0'
+  workflow_dispatch:
 jobs:
   tidy:
     name: Enforce Tidyness
@@ -106,7 +107,7 @@ jobs:
       - uses: mmore500/actions-setup-docker@94429ebc8d9edb4e8c8afb2667bce1e89435f74f
       - run: docker build -t devosoft/empirical .
       - run: docker ps -a
-      - run: sudo docker run --name empirical devosoft/empirical /bin/bash -c "set -o pipefail && cd /opt/Empirical/doc && make html coverage | ./headtail.sh && python /opt/Empirical/doc/parse_documentation_coverage.py /opt/Empirical/doc/_build/doc-coverage.json >> /opt/Empirical/doc-coverage.json"
+      - run: sudo docker run --name empirical devosoft/empirical /bin/bash -c "set -o pipefail && cd /opt/Empirical/doc && make html coverage | ./headtail.sh && python3 /opt/Empirical/doc/parse_documentation_coverage.py /opt/Empirical/doc/_build/doc-coverage.json >> /opt/Empirical/doc-coverage.json"
       - run: sudo docker cp empirical:/opt/Empirical/doc-coverage.json .
       - uses: sylvanld/action-storage@v1
         if: github.ref == 'refs/heads/master'

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: doc/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: doc/requirements.txt

Dockerfile

@@ -1,5 +1,5 @@
 # Pull base image.
-FROM ubuntu:bionic-20210416
+FROM ubuntu:focal-20230412
 
 COPY . /opt/Empirical
 
@@ -8,6 +8,7 @@ SHELL ["/bin/bash", "-c"]
 # Prevent interactive time zone config.
 # adapted from https://askubuntu.com/a/1013396
 ENV DEBIAN_FRONTEND=noninteractive
+ENV SPHINXBUILD="python3.10 -m sphinx"
 
 RUN \
   echo 'Acquire::http::Timeout "60";' >> "/etc/apt/apt.conf.d/99timeout" \
@@ -31,22 +32,21 @@ RUN \
     && \
   rm -rf /var/lib/apt/lists/* \
     && \
-  find /etc/apt -type f -name '*.list' -exec sed -i 's/\(^deb.*-backports.*\)/#\1/; s/\(^deb.*-updates.*\)/#\1/; s/\(^deb.*-proposed.*\)/#\1/; s/\(^deb.*-security.*\)/#\1/' {} + \
-    && \
   apt-get update -y \
     && \
-  apt-get install -y software-properties-common=0.96.24.32.1 \
+  apt-get install -y software-properties-common \
     && \
   add-apt-repository -y ppa:ubuntu-toolchain-r/test \
     && \
+  add-apt-repository -y ppa:deadsnakes/ppa \
+    && \
   apt-get update -y \
     && \
   apt-get install --no-install-recommends --allow-downgrades -y \
-    dpkg-dev \
-    libc6=2.27-3ubuntu1 \
-    libc6-dev \
-    libc6-dbg \
     build-essential \
+    dpkg-dev \
+    g++-11 \
+    libc6 \
     xvfb \
     x11vnc \
     x11-xkb-utils \
@@ -60,21 +60,14 @@ RUN \
     libnss3 \
     lsb-release \
     xdg-utils \
-    g++-8=8-20180414-1ubuntu2 \
-    gcc-8-base=8-20180414-1ubuntu2 \
-    cpp-8=8-20180414-1ubuntu2 \
-    gcc-8=8-20180414-1ubuntu2 \
-    gcc-8-base=8-20180414-1ubuntu2 \
-    libgcc-8-dev \
-    libstdc++-8-dev \
     cmake \
-    python-virtualenv \
-    python-pip-whl \
-    python-pip \
-    python-setuptools \
+    python3-distutils \
     python3-setuptools \
     python3-virtualenv \
     python3-pip \
+    'python3\.10' \
+    'python3\.10-distutils' \
+    'python3\.10-venv' \
     nodejs \
     npm \
     tar \
@@ -84,7 +77,7 @@ RUN \
     doxygen \
     curl \
     perl \
-    perl-base=5.26.1-6 \
+    perl-base \
     git \
     htop \
     man \
@@ -162,25 +155,47 @@ ENV DISPLAY :99
 RUN echo 'kernel.unprivileged_userns_clone=1' > /etc/sysctl.d/userns.conf
 
 RUN \
-  update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-8 90 \
+  update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 90 \
   && \
   npm install -g n \
   && \
   n 14.17 \
   && \
+  hash -r \
+  && \
   export python="/usr/bin/python3" \
   && \
   npm install source-map \
   && \
   echo "finalized set up dependency versions"
 
 RUN \
-  pip install wheel==0.30.0 \
+  curl -sS https://bootstrap.pypa.io/get-pip.py | python3 \
+    && \
+  curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10 \
+    && \
+  pip install --upgrade --force-reinstall pip virtualenv \
+    && \
+  pip3 install --upgrade --force-reinstall pip virtualenv \
+    && \
+  python3.10 -m pip install --upgrade --force-reinstall pip virtualenv \
     && \
-  pip3 install wheel==0.30.0 \
+  python3 -m pip install --upgrade --force-reinstall pip virtualenv \
+    && \
+  pip install wheel==0.30.0 six==1.16.0 \
+    && \
+  pip3 install wheel==0.30.0 six==1.16.0 \
+    && \
+  python3.10 -m pip install wheel==0.30.0 six==1.16.0 \
+    && \
+  python3 -m pip install wheel==0.30.0 six==1.16.0 \
     && \
   pip3 install -r /opt/Empirical/doc/requirements.txt \
     && \
+  python3.10 -m pip install -r /opt/Empirical/doc/requirements.txt \
+    && \
+  python3 -m pip install -r /opt/Empirical/doc/requirements.txt \
+    && \
   echo "installed documentation build requirements"
 
 RUN \
@@ -190,13 +205,19 @@ RUN \
     && \
   git submodule init \
     && \
-  git submodule update -f \
+  echo "nameserver 8.8.8.8" > /etc/resolv.conf \
+    && \
+  n=0; until [ $n -ge 3 ]; do git submodule update -f && break || ((n++)); sleep 5; done; if [ $n -eq 3 ]; then echo "Update failed after 3 attempts."; else echo "Update successful!"; fi \
     && \
   echo "initialized submodules"
 
 RUN \
   cd /opt/Empirical \
     && \
+  curl -sS https://bootstrap.pypa.io/get-pip.py | python3 \
+    && \
+  python3 -m pip install virtualenv \
+    && \
   make install-test-dependencies \
     && \
   echo "installed test dependencies"

doc/conf.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Empirical documentation build configuration file, created by
@@ -22,6 +22,7 @@
 import sphinx_rtd_theme
 import subprocess
 import sys
+import textwrap
 
 # -- General configuration ---------------------------------------------
 
@@ -60,7 +61,10 @@
     # TIP: if using the sphinx-bootstrap-theme, you need
     # "treeViewIsBootstrap": True,
     "exhaleExecutesDoxygen": True,
-    "exhaleDoxygenStdin":    "INPUT = ../include"
+    "exhaleDoxygenStdin": textwrap.dedent("""
+        INPUT = ../include
+        EXCLUDE_SYMBOLS += internal __impl_* *impl *IMPL *_IMPL_* *Impl
+    """)
 }
 
 # Tell sphinx what the primary language being documented is.

doc/library/Evolve/evolve.md

@@ -0,0 +1,38 @@
+# Evolution tools
+
+## World
+
+```{eval-rst}
+.. doxygenfile:: emp/Evolve/World.hpp
+  :project: Empirical
+  :no-link:
+```
+
+## Systematics Manager
+
+```{include} systematics.md
+```
+
+### Systematics API
+
+```{eval-rst}
+.. doxygenfile:: emp/Evolve/Systematics.hpp
+  :project: Empirical
+  :no-link:
+```
+
+## NK
+
+```{eval-rst}
+.. doxygenfile:: emp/Evolve/NK.hpp
+  :project: Empirical
+  :no-link:
+```
+
+## Selection
+
+```{eval-rst}
+.. doxygenfile:: emp/Evolve/World_select.hpp
+  :project: Empirical
+  :no-link:
+```