Merge pull request #484 from devosoft/documentation

Isolate docs changes from MABE changes in #480

Author: mmore500

Diff for: .github/workflows/CI.yml

@@ -7,12 +7,13 @@ on:
       - '**'
   schedule:
     - cron: '0 0 * * 0'
+  workflow_dispatch:
 jobs:
   tidy:
     name: Enforce Tidyness
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           submodules: 'recursive'
       - run: sudo apt-get update -qq
@@ -47,7 +48,7 @@ jobs:
       CXX: ${{ matrix.cxx }}
       TEST_SET: ${{ matrix.test-set }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           submodules: 'recursive'
       - name: Set up GCC
@@ -68,7 +69,7 @@ jobs:
     name: Web Tests
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           submodules: 'recursive'
       - name: Set up GCC
@@ -86,7 +87,7 @@ jobs:
     name: Measure Test Coverage
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           submodules: 'recursive'
       - run: sudo apt-get update -qq
@@ -138,17 +139,33 @@ jobs:
       # github actions requires root to access mounted volumes
       options: --user root
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v3
         with:
           submodules: 'recursive'
-      - run: |
-          make -C doc html coverage | ./doc/headtail.sh
-          python doc/parse_documentation_coverage.py doc/_build/doc-coverage.json >> doc-coverage.json
+      - run: doxygen
+      - run: cd doc && python make_md.py
+      - run: cd doc && make html | ./headtail.sh
+      - run: cd doc && make coverage
+      - run: ls doc/ && ls doc/_build
+      - run: cd doc && python parse_documentation_coverage.py _build/doc-coverage.json >> doc-coverage.json
+      - uses: actions/upload-artifact@v2
+        with:
+          name: doc-coverage
+          path: doc/doc-coverage.json
+  deploy-documentation-coverage:
+    name: Deploy Documentation Coverage
+    runs-on: ubuntu-22.04
+    if: github.ref == 'refs/heads/master'
+    needs: test-documentation
+    steps:
+      - uses: actions/download-artifact@v2
+        with:
+          name: doc-coverage
+          path: data
       - uses: sylvanld/action-storage@v1
-        if: github.ref == 'refs/heads/master'
         with:
-          src: doc-coverage.json
-          dst: stats/doc-coverage.json
+          src: data/doc-coverage.json
+          dst: data/doc-coverage.json
   deploy-container:
     name: Deploy to DockerHub and ghcr.io
     runs-on: ubuntu-22.04

Diff for: .readthedocs.yaml

@@ -2,22 +2,24 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-#Required
+# Required
 version: 2
 
+# Set the version of Python and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.7"
+    python: "3.10"
+  jobs:
+    pre_build:
+      - doxygen
+      - cd doc && python make_md.py
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-  configuration: doc/conf.py
+   configuration: doc/conf.py
 
-# Optionally build your docs in additional formats such as PDF
-formats: []
-
-# Optionally set the version of Python and requirements required to build your docs
+# Optionally declare the Python requirements required to build your docs
 python:
-  install:
-    - requirements: doc/requirements.txt
+   install:
+   - requirements: doc/requirements.txt

Diff for: 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,10 @@ 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-setuptools \
-    python3-virtualenv \
-    python3-pip \
+    'python3\.10' \
+    'python3\.10-distutils' \
+    'python3\.10-venv' \
     nodejs \
     npm \
     tar \
@@ -84,7 +73,7 @@ RUN \
     doxygen \
     curl \
     perl \
-    perl-base=5.26.1-6 \
+    perl-base \
     git \
     htop \
     man \
@@ -97,13 +86,22 @@ RUN \
     ssh-client \
     libasound2 \
     gpg-agent \
+    doxygen \
     && \
   apt-get clean \
     && \
   rm -rf /var/lib/apt/lists/* \
     && \
   echo "installed apt packages"
 
+# Set Python 3.10 as the default version of Python 3
+RUN \
+  update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1 \
+  && \
+  update-alternatives --set python3 /usr/bin/python3.10 \
+  && \
+  ln -s /usr/bin/python3.10 /usr/bin/python
+
 RUN \
   echo $' \n\
 XVFB=/usr/bin/Xvfb \n\
@@ -162,24 +160,34 @@ 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 \
+  python3.10 --version \
+    && \
+  python3 --version \
     && \
-  pip3 install wheel==0.30.0 \
+  curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10 \
     && \
-  pip3 install -r /opt/Empirical/doc/requirements.txt \
+  python3.10 -m pip install --upgrade --force-reinstall pip virtualenv \
+    && \
+  python3.10 -m pip install wheel==0.30.0 six==1.16.0 \
+    && \
+  python3.10 -m pip install -r /opt/Empirical/third-party/requirements.txt \
+    && \
+  python3.10 -m pip install -r /opt/Empirical/doc/requirements.txt \
     && \
   echo "installed documentation build requirements"
 
@@ -190,13 +198,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"
@@ -254,13 +268,6 @@ RUN \
   && \
   echo "installed karma-firefox-launcher"
 
-# @mmore500 10-2021: python3 -m pip fixes UnicodeDecodeError
-# when installing charset-normalizer from github
-RUN \
-  python3 -m pip install -r /opt/Empirical/third-party/requirements.txt \
-    && \
-  echo "installed documentation build requirements"
-
 # Perform any further action as an unprivileged user.
 # adapted from https://stackoverflow.com/a/27703359
 # and https://superuser.com/a/235398