Update documentation system (migrate to Mkdocs)

.github/workflows/build-and-test.yml

@@ -53,27 +53,23 @@ jobs:
       - name: Get number of CPU cores # Can replace when CMake is upgraded to 3.29
         uses: SimenB/github-actions-cpu-cores@v2
         id: cpu-cores
-      - name: Build CSE
-        uses: ./.github/actions/build-cse
+      # - name: Setup Mesa3D
+      #   uses: bigladder/github-actions/setup-mesa3d@main
+      #   with:
+      #     install-directory: msvc
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
         with:
-          arch: ${{ matrix.arch }}
-          config: ${{ matrix.config }}
-          compiler: ${{ matrix.compiler }}
-      - name: Build cse_tests.exe (unit tests)
-        run: cmake -DBUILD_ARCHITECTURE=${{ matrix.arch }} -DCONFIGURATION=${{ matrix.config }} -DTARGET_NAME=cse_tests -DBUILD_DIRECTORY=build -P cmake/build.cmake
+          python-version: "3.13"
+      - name: Build CSE
+        run: cmake -DBUILD_ARCHITECTURE=${{ matrix.arch }} -DCOMPILER_ID=${{ matrix.compiler }} -DCONFIGURATION=${{ matrix.config }} -DBUILD_DIRECTORY=build -DBUILD_DOCS_WITH_ALL=ON -P cmake/configure-and-build.cmake
       - name: Upload executable artifact
         uses: actions/upload-artifact@v4
         with:
-          name: CSE_${{ matrix.os }}-${{ matrix.os_ver }}-${{ matrix.arch }}bit_${{ matrix.config }}
+          name: CSE-${{ matrix.os }}-${{ matrix.os_ver }}-${{ matrix.arch }}bit-${{ matrix.config }}
           path: |
             build/CSE*
             build/cse*
-      - name: Build wcmp executable
-        run: cmake -DBUILD_ARCHITECTURE=${{ matrix.arch }} -DCONFIGURATION=${{ matrix.config }} -DTARGET_NAME=wcmp -DBUILD_DIRECTORY=build -P cmake/build.cmake
-      # - name: Setup Mesa3D
-      #   uses: bigladder/github-actions/setup-mesa3d@main
-      #   with:
-      #     install-directory: msvc
       - name: Test
         id: test
         run: ctest -C ${{ matrix.config }} -j ${{ steps.cpu-cores.outputs.count }} --output-on-failure -E shadetest  # CI can't do GPU calcs at this time (the steps above get us close, but throws an exception on destruction)
@@ -87,34 +83,12 @@ jobs:
           path: |
             test/*.rep
             test/*.REP
-      - name: Check test failure
-        if: steps.test.outcome == 'failure'
-        run: exit 1
-  build-doc:
-    strategy:
-      fail-fast: false
-    name: Build CSE documentation
-    needs: build-cse
-    if: ${{ always() }}
-    runs-on: windows-2022
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Configure CMake
-        run: cmake -P cmake/configure.cmake
-      - name: Download CSE artifact
-        uses: ./.github/actions/download-cse-artifact
-      - name: Build docs
-        uses: ./.github/actions/build-docs
-      - name: Run coverage check
-        run: rake coverage
-        working-directory: doc
-        env:
-          CSE_EXE_PATH: ..\\build\\CSE.exe
       - name: Upload documentation
         uses: actions/upload-artifact@v4
         with:
-          name: Documentation
+          name: Documentation-${{ matrix.os }}-${{ matrix.os_ver }}-${{ matrix.arch }}
           path: |
-                doc/output
-                !doc/output/.git
+            doc/build
+      - name: Check test failure
+        if: steps.test.outcome == 'failure'
+        run: exit 1

.github/workflows/release.yml

@@ -18,19 +18,21 @@ jobs:
         with:
           fetch-depth: 0
           submodules: recursive
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
       - name: Build CSE
-        uses: ./.github/actions/build-cse
+        run: cmake -DBUILD_ARCHITECTURE=32 -DCOMPILER_ID=msvc -DCONFIGURATION=Release -DBUILD_DIRECTORY=build -DBUILD_DOCS_WITH_ALL=ON -P cmake/configure-and-build.cmake
       - name: Upload executable to release assets
         uses: softprops/action-gh-release@v2
         with:
           files: build/CSE.exe
-      - name: Build docs
-        uses: ./.github/actions/build-docs
       - name: Update gh-pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: doc/output
+          publish_dir: doc/build
           user_name: 'cse-ci'
           user_email: 'ci@cse.org'
           full_commit_message: "Update docs for ${{ github.event.release.tag_name }}."

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.9.9
+  hooks:
+    # Run the formatter (automatically fixes in-place)
+    - id: ruff-format
+    # Run the linter
+    - id: ruff
+      args: [ --fix ]
+- repo: local
+  hooks:
+    - id: mypy
+      name: mypy
+      entry: uv run mypy
+      require_serial: true
+      language: system
+      types: [python]

.python-version

@@ -0,0 +1 @@
+3.13

CMakeLists.txt

@@ -92,3 +92,16 @@ set_directory_properties(PROPERTIES VS_STARTUP_PROJECT CSE)
 enable_testing()
 
 add_subdirectory(test)
+
+# Documentation
+set(cse_documentation_build_options "DoNotBuild;BuildWithAll;BuildSeparately")
+set(CSE_BUILD_DOCUMENTATION "BuildSeparately" CACHE STRING "Choose when/if to build documentation (${cse_documentation_build_options}).")
+set_property(CACHE CSE_BUILD_DOCUMENTATION PROPERTY STRINGS ${cse_documentation_build_options})
+
+if(NOT CSE_BUILD_DOCUMENTATION IN_LIST cse_documentation_build_options)
+  message(FATAL_ERROR "CSE_BUILD_DOCUMENTATION must be one of ${cse_documentation_build_options}")
+endif()
+
+if(NOT CSE_BUILD_DOCUMENTATION STREQUAL "DoNotBuild")
+  add_subdirectory(doc)
+endif()

cmake/CSEVersion.cmake

@@ -45,7 +45,6 @@ if (GIT_TAG MATCHES "^v[0-9]+\\.[0-9]+\\.[0-9]+(\\-[0-9A-Za-z-]+)?$")
   string(REGEX REPLACE "^v[0-9]+\\.[0-9]+\\.([0-9]+)(\\-[0-9A-Za-z-]+)?$" "\\1" CSEVRSN_PATCH "${GIT_TAG}")
   if (GIT_TAG MATCHES "^v[0-9]+\\.[0-9]+\\.[0-9]+(\\-[0-9A-Za-z-]+)$")
     string(REGEX REPLACE "^v[0-9]+\\.[0-9]+\\.[0-9]+(\\-[0-9A-Za-z-]+)$" "\\1" CSEVRSN_PRERELEASE "${GIT_TAG}")
-    message(STATUS "CSEVRSN_PRERELEASE is ${CSEVRSN_PRERELEASE}")
   endif()
 elseif(GIT_TAG MATCHES "^cse\\.[0-9]+$")
   # old version scheme

cmake/configure.cmake

@@ -14,6 +14,10 @@ if (DEFINED EXECUTABLE_DIRECTORY)
     set(configure_command ${configure_command} -DCSE_EXECUTABLE_DIRECTORY=${EXECUTABLE_DIRECTORY})
 endif ()
 
+if (DEFINED BUILD_DOCS_WITH_ALL)
+    set(configure_command ${configure_command} -DCSE_BUILD_DOCUMENTATION=BuildWithAll)
+endif ()
+
 if ("${CMAKE_HOST_SYSTEM_NAME}" STREQUAL "Windows")
     if (${COMPILER_ID} STREQUAL "msvc")
         # Explicitly set versions to guarantee computational stability

doc/.gitignore

@@ -1,9 +1,18 @@
 build/
-output/
-node_modules/
 config.yaml
-erb-out.txt
-documentation-coverage-report.txt
-package-lock.json
 
+*.egg*/
+.doit.*
+.pytest_cache/
+.vscode/
+.venv/
+__pycache__/
+dist/
 
+**/probe-definitions/*.md
+!**/probe-definitions/index.md
+
+probes.txt
+cullist.txt
+
+.DS_Store

doc/CMakeLists.txt

@@ -0,0 +1,17 @@
+find_program(UV_EXECUTABLE NAMES uv REQUIRED)
+
+if(CSE_BUILD_DOCUMENTATION STREQUAL "BuildWithAll")
+    set(build_with_all_string "ALL")
+endif()
+
+add_custom_target(
+        cse_documentation
+        ${build_with_all_string}
+        COMMAND ${UV_EXECUTABLE} run mkdocs build
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src"
+)
+
+add_test(NAME documentation.coverage
+        COMMAND ${UV_EXECUTABLE} run coverage.py --path_to_cse $<TARGET_FILE:CSE> --path_to_input_data "docs/input-data"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src"
+)