Update docs image, move it to hub.docker.com/u/libfn (#129)

* Update README.md
* Rewrite ci-docs
* Minor Dockerfile changes
* Add docs to ci workflow
* Update docs workflow
* Minor fixes in license workflow

Author: Bronek

.github/workflows/ci.yml

@@ -3,8 +3,9 @@ name: ci
 on:
   schedule:
   # https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07
-  # This is meant to run at 13:17 on 11th of every month
+  # This is meant to run at 13:17 UTC on 11th and 26th of every month
     - cron: '17 13 11 * *'
+    - cron: '17 13 26 * *'
   push:
     branches:
       - main
@@ -17,6 +18,7 @@ on:
 env:
   REGISTRY_IMAGE_BUILD: libfn/ci-build
   REGISTRY_IMAGE_PRE_COMMIT: libfn/ci-pre-commit
+  REGISTRY_IMAGE_DOCS: libfn/ci-docs
 
 jobs:
 
@@ -251,3 +253,108 @@ jobs:
       - name: Inspect image
         run: |
           docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE_PRE_COMMIT }}:${{ steps.meta.outputs.version }}
+
+  docs:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - linux/amd64
+          - linux/arm64
+
+    steps:
+      - name: Prepare
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY_IMAGE_DOCS }}
+          tags: |
+            type=schedule,pattern={{date 'YYYYMMDD'}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          platforms: ${{ matrix.platform }}
+          context: "{{defaultContext}}:ci/docs/"
+          file: Dockerfile
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ env.REGISTRY_IMAGE_DOCS }},push-by-digest=true,name-canonical=true,push=true
+          sbom: true
+          provenance: mode=max
+
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-docs-${{ env.PLATFORM_PAIR }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge-docs:
+    runs-on: ubuntu-latest
+    needs:
+      - docs
+
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-docs-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY_IMAGE_DOCS }}
+          tags: |
+            type=schedule,pattern={{date 'YYYYMMDD'}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.REGISTRY_IMAGE_DOCS }}@sha256:%s ' *)
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE_DOCS }}:${{ steps.meta.outputs.version }}

.github/workflows/docs.yml

@@ -19,25 +19,20 @@ permissions:
   pages: write
   id-token: write
 
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
-
 jobs:
   generate_docs:
-    name: Generate and upload docs
-    runs-on: ubuntu-20.04
-    container:
-      image: godexsoft/functional-ci:0.0.4
+    runs-on:
+      group: default
+    strategy:
+      fail-fast: false
+    container: libfn/ci-docs:latest
     steps:
       - uses: actions/checkout@v3
         with:
           submodules: 'true'
 
       - name: Export docs
         continue-on-error: false
-        shell: bash
-        id: run_cmake
         run: |
           mkdir .build
           cd .build

.github/workflows/licence.yml

@@ -11,6 +11,7 @@ on:
       - 'CMakeLists.txt'
       - 'cmake/**'
       - '.fossa.yml'
+      - 'LICENSE.md'
   pull_request:
     branches:
       - main
@@ -21,6 +22,7 @@ on:
       - 'CMakeLists.txt'
       - 'cmake/**'
       - '.fossa.yml'
+      - 'LICENSE.md'
   workflow_dispatch:
     inputs:
       run_licence_check:
@@ -59,5 +61,6 @@ jobs:
     - name: What happened?
       if: failure() && steps.assert.outcome == 'failure'
       run:
-        echo "You branch appear to have attempted to modify ${LICENCE_FILE}"
+        echo "Your pull request appear to have attempted to modify ${LICENCE_FILE}"
+        echo "If you want your name added to ${LICENCE_FILE}, please ask project maintainers."
         exit 1

.pre-commit-config.yaml

@@ -5,19 +5,16 @@
 # pre-commit install
 # pre-commit install-hooks
 #
-# precommit hooks installation
-#
-# - pre-commit autoupdate
-#
-# - pre-commit run black
-#
 # continuous integration
 # ======================
 #
 # - pre-commit run --all-files
 #
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
+#
+# NOTE repo and rev listed below must match ci/pre-commit/requirements.txt
+#
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v5.0.0

README.md

@@ -50,24 +50,31 @@ The maintainers are unable to guarantee that no significant refactoring will eve
 [ripple]: https://ripple.com/
 
 ## Pre-commit
-This repository supports [pre-commit](https://pre-commit.com/) to install git commit hooks which will run checks on the repository (currently just clang-format).  Pre-commit will install git commit hooks locally so that they run on each commit. To set up locally you configure a virtual environment, install the requirements and run pre-commit install.
 
-```
+This repository uses [pre-commit](https://pre-commit.com/) to enforce formatting of the C++ source code and perform other checks. The details can be seen in `.pre-commit-config.yaml`. To install git commit hooks, which will run checks on the repository as you commit changes:
+
+* configure a Python virtual environment
+* install the requirements from `ci/pre-commit/requirements.txt`
+* run `pre-commit install` in your local repository
+
+```bash
 # Set up a virtual environment to install pre-commit
 python3 -m venv .venv
-source ./.venv/bin/activate
-pip install pre-commit
+source .venv/bin/activate
+pip install -r ci/pre-commit/requirements.txt
 # Now install the pre-commit hooks locally
 pre-commit install
 ```
 
-You can run the check manually as follows:
-```
+You can run all checks manually as follows:
+
+```bash
 # Source the virtual environment to access pre-commit
-source ./.venv/bin/activate
+source .venv/bin/activate
 # Run pre-commit on local files.
 pre-commit run --all-files
 ```
 
 ## License
+
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Flibfn%2Ffunctional.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Flibfn%2Ffunctional?ref=badge_large)

ci/build/clang/Dockerfile

@@ -1,6 +1,7 @@
 FROM debian:bookworm
 
 ARG CLANG_RELEASE=19
+ENV CLANG_RELEASE=${CLANG_RELEASE}
 ENV DEBIAN_FRONTEND=noninteractive
 RUN set -ex ;\
     apt-get update ;\
@@ -32,6 +33,7 @@ ENV CMAKE_BUILD_TYPE=Debug
 
 WORKDIR /work
 ARG CATCH_RELEASE=3.7.1
+ENV CATCH_RELEASE=${CATCH_RELEASE}
 RUN set -ex ;\
     git clone https://github.com/catchorg/Catch2.git ;\
     cd Catch2 ;\

ci/build/gcc/Dockerfile

@@ -3,16 +3,15 @@ ARG GCC_DIST=${GCC_RELEASE}-bookworm
 FROM gcc:${GCC_DIST} AS gcc
 RUN set -ex ;\
     find /usr/local/ -type f ;\
-    cat /etc/ld.so.conf.d/000-local-lib.conf ;\
+    cat /etc/ld.so.conf.d/* ;\
     cat /etc/os-release ;\
     /usr/local/bin/gcc --version
 
 FROM debian:bookworm
 COPY --from=gcc /usr/local/ /usr/local/
-COPY --from=gcc /etc/ld.so.conf.d/000-local-lib.conf /etc/ld.so.conf.d/000-local-lib.conf
+COPY --from=gcc /etc/ld.so.conf.d/ /etc/ld.so.conf.d/
 
 WORKDIR /root
-ENV DEBIAN_FRONTEND=noninteractive
 RUN set -ex ;\
     ldconfig -v ;\
     dpkg-divert --divert /usr/bin/gcc.orig --rename /usr/bin/gcc ;\
@@ -32,6 +31,7 @@ RUN set -ex ;\
     update-alternatives --auto cc ;\
     update-alternatives --auto gcc
 
+ENV DEBIAN_FRONTEND=noninteractive
 RUN set -ex ;\
     apt-get update ;\
     apt-get install -y --no-install-recommends \

ci/docs/Dockerfile

@@ -1,23 +1,57 @@
-FROM fedora:39
+ARG GCC_RELEASE=14
+ARG GCC_DIST=${GCC_RELEASE}-bookworm
+FROM gcc:${GCC_DIST} AS gcc
+RUN set -ex ;\
+    find /usr/local/ -type f ;\
+    cat /etc/ld.so.conf.d/* ;\
+    cat /etc/os-release ;\
+    /usr/local/bin/gcc --version
+
+FROM debian:bookworm
+COPY --from=gcc /usr/local/ /usr/local/
+COPY --from=gcc /etc/ld.so.conf.d/ /etc/ld.so.conf.d/
 
 WORKDIR /root
+RUN set -ex ;\
+    ldconfig -v ;\
+    dpkg-divert --divert /usr/bin/gcc.orig --rename /usr/bin/gcc ;\
+    dpkg-divert --divert /usr/bin/g++.orig --rename /usr/bin/g++ ;\
+    dpkg-divert --divert /usr/bin/gfortran.orig --rename /usr/bin/gfortran ;\
+    update-alternatives --install /usr/bin/cc cc /usr/local/bin/gcc 999 ;\
+    update-alternatives --install \
+      /usr/bin/gcc gcc /usr/local/bin/gcc 100 \
+      --slave /usr/bin/g++ g++ /usr/local/bin/g++ \
+      --slave /usr/bin/gcc-ar gcc-ar /usr/local/bin/gcc-ar \
+      --slave /usr/bin/gcc-nm gcc-nm /usr/local/bin/gcc-nm \
+      --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/local/bin/gcc-ranlib \
+      --slave /usr/bin/gcov gcov /usr/local/bin/gcov \
+      --slave /usr/bin/gcov-tool gcov-tool /usr/local/bin/gcov-tool \
+      --slave /usr/bin/gcov-dump gcov-dump /usr/local/bin/gcov-dump \
+      --slave /usr/bin/lto-dump lto-dump /usr/local/bin/lto-dump ;\
+    update-alternatives --auto cc ;\
+    update-alternatives --auto gcc
 
-RUN dnf -y update ;\
-    dnf -y install redhat-lsb python3.11 gcc libstdc++-static ccache \
-    vim wget sudo curl git grep sed gdb zsh cmake doxygen ninja-build \
-    unzip java-latest-openjdk clang git-clang-format clang-tools-extra llvm ;\
-    dnf -y clean all
+ENV DEBIAN_FRONTEND=noninteractive
+RUN set -ex ;\
+    apt-get update ;\
+    apt-get install -y --no-install-recommends \
+      ca-certificates gpg gpg-agent wget vim \
+      cmake ninja-build binutils libc6-dev git \
+      openjdk-17-jdk doxygen unzip ;\
+    apt-get clean
 
-# Fail build if unexpected gcc version
-RUN gcc --version | grep -E "^gcc \(GCC\) 13"
+ARG ZNAI_RELEASE=1.73
+ENV ZNAI_RELEASE=${ZNAI_RELEASE}
+WORKDIR /work
+RUN set -ex ;\
+    DIST="https://repo.maven.apache.org/maven2/org/testingisdocumenting/znai/znai-dist" ;\
+    wget ${DIST}/${ZNAI_RELEASE}/znai-dist-${ZNAI_RELEASE}-znai.zip ;\
+    unzip znai-dist-${ZNAI_RELEASE}-znai.zip -d znai_tmp ;\
+    mv znai_tmp/dist /opt/znai ;\
+    rm -rf znai-dist-${ZNAI_RELEASE}-znai.zip znai_tmp
 
-RUN wget https://repo.maven.apache.org/maven2/org/testingisdocumenting/znai/znai-dist/1.70/znai-dist-1.70-znai.zip ;\
-    unzip znai-dist-1.70-znai.zip -d znai_tmp; mv znai_tmp/dist /opt/znai ;\
-    rm -rf znai-dist-1.70-znai.zip znai_tmp
 ENV PATH=/opt/znai:${PATH}
-
 ENV CC=/usr/bin/gcc
 ENV CXX=/usr/bin/g++
-ENV CMAKE_GENERATOR='Ninja'
-ENV CMAKE_C_COMPILER=${CC}
-ENV CMAKE_CXX_COMPILER=${CXX}
+ENV CMAKE_GENERATOR=Ninja
+ENV CMAKE_BUILD_TYPE=Debug

ci/pre-commit/requirements.txt

@@ -1,4 +1,4 @@
 pre-commit<5
-# NOTE versions listed below must match .pre-commit-config.yaml
+# NOTE packages and versions listed below must match .pre-commit-config.yaml
 clang-format==18.1.8
 pre-commit-hooks==5.0.0