YT-CPPAP-40: Documentation deployment

.github/workflows/documentation.yaml

@@ -1,33 +1,77 @@
 name: documentation
+
 on:
   pull_request:
     branches:
-      - master
-
+      - '*'
+  push:
+    tags:
+      - 'v*'
 
 jobs:
   build-doc:
-    name: Build documentation
+    name: Build and validate documentation
     runs-on: ubuntu-24.04
 
     steps:
-      - name: Check out current branch
+      - name: Check out repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
           submodules: recursive
 
-      - name: Sync submodules to HTTPS
-        run: git submodule sync --recursive
-
-      - name: Update submodules
-        run: git submodule update --init --recursive
+      - name: Set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
 
       - name: Install dependencies
         run: sudo apt install doxygen -y
 
+      - name: Validate the project version
+        run: |
+          VERSION=$(python3 scripts/check_version.py)
+          echo "project version = $VERSION"
+
       - name: Run doxygen
         run: doxygen Doxyfile
 
-      - name: Verify documentation
+      - name: Validate output
         run: test -d documentation && test -f documentation/index.html
+
+  deploy-doc:
+    name: Deploy documentation
+    if: github.event_name == 'push'
+    needs: build-doc
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: sudo apt install doxygen -y
+
+      - name: Extract version from CMakeLists.txt
+        run: |
+          VERSION=$(python3 scripts/check_version.py)
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Run doxygen
+        run: doxygen Doxyfile
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./documentation
+          publish_branch: gh-pages
+          destination_dir: ${{ env.VERSION }}

CMakeLists.txt

@@ -7,7 +7,7 @@ else()
 endif()
 
 project(cpp-ap
-    VERSION 2.2.4
+    VERSION 2.2.5
     DESCRIPTION "Command-line argument parser for C++20"
     HOMEPAGE_URL "https://github.com/SpectraL519/cpp-ap"
     LANGUAGES CXX

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = "CPP-AP"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.2.4
+PROJECT_NUMBER         = 2.2.5
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

README.md

@@ -42,7 +42,7 @@ Command-line argument parser for C++20
 - [Dev notes](/docs/dev_notes.md)
   - [Building and testing](/docs/dev_notes.md#building-and-testing)
   - [Formatting](/docs/dev_notes.md#formatting)
-  - [Documentation](/docs/dev_notes.md#documentation)
+  - [Documentation](https://spectral519.github.io/cpp-ap/2.2.4/)
 
 <br />
 

docs/dev_notes.md

@@ -61,6 +61,9 @@ python scripts/format.py --help
 
 ## Documentation
 
+> [!INFO]
+> You can view the online documentation [here](https://spectral519.github.io/cpp-ap/2.2.4/).
+
 The documentation for this project can be generated using Doxygen, styled with a custom [fork](https://github.com/SpectraL519/doxygen-awesome-css/tree/theme-alignment) of the [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css) theme.
 
 ### Prerequisites

scripts/check_version.py

@@ -0,0 +1,55 @@
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+def get_cmake_version(cmake_path: Path):
+    text = cmake_path.read_text()
+    match = re.search(r'project\s*\([^\)]*VERSION\s+(\d+\.\d+\.\d+)', text, re.IGNORECASE)
+    if match:
+        return match.group(1)
+    raise ValueError(f"Could not find project version in {cmake_path}")
+
+
+def get_doxy_version(doxyfile_path: Path):
+    text = doxyfile_path.read_text()
+    match = re.search(r'^\s*PROJECT_NUMBER\s*=\s*("?)([\d\.]+)\1', text, re.MULTILINE)
+    if match:
+        return match.group(2)
+    raise ValueError(f"Could not find PROJECT_NUMBER in {doxyfile_path}")
+
+
+def main(cmake: Path, doxygen: Path):
+    try:
+        cmake_version = get_cmake_version(cmake)
+        doxy_version = get_doxy_version(doxygen)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if cmake_version != doxy_version:
+        print(f"Version mismatch: CMakeLists.txt = {cmake_version}, Doxyfile = {doxy_version}", file=sys.stderr)
+        sys.exit(1)
+
+    print(cmake_version) # print the version to stdout for shell capture
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-c", "--cmake",
+        type=Path,
+        default="CMakeLists.txt",
+        nargs=1,
+        help="Path to the root CMake file"
+    )
+    parser.add_argument(
+        "-d", "--doxygen",
+        type=Path,
+        default="Doxyfile",
+        nargs=1,
+        help="Path to the doxygen config file"
+    )
+
+    main(**vars(parser.parse_args()))