Merge branch '282-docs-doxygen-reports-and-aliases' into staging

Author: steven varga

.github/workflows/docs.yml

@@ -8,32 +8,10 @@ permissions:
   contents: write
 
 jobs:
-  # MkDocs — conceptual docs, architecture pages, guides
-  deploy-mkdocs:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repo
-        uses: actions/checkout@v6
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.x'
-
-      - name: Install MkDocs + Material theme
-        run: pip install mkdocs mkdocs-material
-
-      - name: Build MkDocs site
-        run: mkdocs build
-
-      - name: Deploy MkDocs to gh-pages root
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          keep_files: true
-
-  # Doxygen — API reference generated from C++ headers
+  # Doxygen — full project documentation site (API reference + curated
+  # I/O+TOPICS axes + COOKBOOK + REPORTS, all generated from headers,
+  # examples, and the doxy/docs/{index,aliases,curated,reports}/ markdown).
+  # Publishes to the gh-pages root; MkDocs has been retired.
   deploy-doxygen:
     runs-on: ubuntu-latest
     steps:
@@ -45,13 +23,43 @@ jobs:
           sudo apt-get update -qq
           sudo apt-get install -y doxygen
 
-      - name: Build Doxygen API reference
-        run: cd doxy && doxygen Doxyfile
+      - name: Checkout repo (with full history so docs-build.sh can resolve git tags)
+        run: |
+          if ! git rev-parse --git-dir >/dev/null 2>&1; then
+            echo "checkout missing — run actions/checkout@v4 above"
+            exit 1
+          fi
+          # actions/checkout@v4 uses depth=1 by default; fetch tags so the
+          # version-deriving git describe in docs-build.sh sees real releases.
+          git fetch --tags --depth=0 origin || true
+
+      - name: Build Doxygen documentation (version from git tag, post-processed)
+        run: scripts/docs-build.sh
+
+      - name: Summarise Doxygen warnings
+        if: always()
+        run: |
+          log=doxy/docs/doxygen/warnings.log
+          if [[ -f $log ]]; then
+            count=$(wc -l < $log)
+            echo "::notice::Doxygen warnings: $count lines (see uploaded artifact 'doxygen-warnings')"
+            head -50 $log || true
+          else
+            echo "::notice::No Doxygen warnings log produced"
+          fi
+
+      - name: Upload Doxygen warnings log
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: doxygen-warnings
+          path: doxy/docs/doxygen/warnings.log
+          if-no-files-found: ignore
+          retention-days: 30
 
-      - name: Deploy Doxygen to gh-pages/api
+      - name: Deploy Doxygen to gh-pages root
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/doxygen/html
-          destination_dir: api
+          publish_dir: ./doxy/docs/doxygen/html
           keep_files: true

.gitignore

@@ -158,5 +158,4 @@ data/
 # =============================================================================
 # Documentation build output
 # =============================================================================
-docs/docs/site
-site/
+doxy/docs/doxygen/

CMakeLists.txt

@@ -16,7 +16,7 @@ endif()
 # embeds it as PROJECT_VERSION rather than a stale hardcoded number.  Falls
 # back to a placeholder when building from a tarball without git history.
 find_package(Git QUIET)
-set(H5CPP_PROJECT_VERSION "1.12.0")
+set(H5CPP_PROJECT_VERSION "1.12.7")
 if(GIT_FOUND AND EXISTS "${CMAKE_SOURCE_DIR}/.git")
     execute_process(
         COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0 --match "v[0-9]*"
@@ -453,25 +453,8 @@ string(TOLOWER "${CPACK_PACKAGE_FILE_NAME}" CPACK_PACKAGE_FILE_NAME)
 include(CPack)
 
 # ─── Developer convenience targets ───────────────────────────────────────────
-find_program(MKDOCS_EXECUTABLE mkdocs)
 find_program(DOXYGEN_EXECUTABLE doxygen)
 
-if(MKDOCS_EXECUTABLE)
-    add_custom_target(docs COMMAND ${MKDOCS_EXECUTABLE} build --config-file ${CMAKE_SOURCE_DIR}/mkdocs.yml --site-dir ${CMAKE_BINARY_DIR}/site
-        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} 
-        COMMENT "Building MkDocs documentation → build/site"
-        VERBATIM
-    )
-    set(MKDOCS_DEV_ADDR "127.0.0.1:8000" CACHE STRING "host:port for mkdocs serve (docs-serve target)")
-    add_custom_target(docs-serve COMMAND ${MKDOCS_EXECUTABLE} serve --livereload
-        --dev-addr ${MKDOCS_DEV_ADDR}
-        --config-file ${CMAKE_SOURCE_DIR}/mkdocs.yml
-        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-        COMMENT "Serving MkDocs with live reload at ${MKDOCS_DEV_ADDR} (Ctrl-C to stop)"
-        VERBATIM
-    )
-endif()
-
 if(DOXYGEN_EXECUTABLE)
     add_custom_target(docs-doxygen COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
         WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/doxy

CONTRIBUTING.md

@@ -111,3 +111,21 @@ A pull request should:
 - document user-visible behavior changes
 
 The preferred merge target for active development is `staging`. Release branches are promoted from `staging` after validation.
+
+## Documentation — alias-first docstrings
+
+H5CPP's API surface is built on overload sets (`h5::write` has ~40 overloads, `h5::read` ~30, `h5::create` ~20). Each carries the same `file_path`, `dataset_path`, `offset`, `stride`, `count`, `block`, `dxpl`, template parameter, return type. Without discipline, the same `@param` block ends up duplicated across dozens of docstrings — and a wording change requires dozens of edits.
+
+To keep docstrings DRY, the project uses a controlled vocabulary of Doxygen aliases defined in `docs/links/*.txt`. Each alias is a single-token expansion that produces a fully-formed `@param` / `@tparam` / `@return` / `@see` block.
+
+The full vocabulary catalog, standard docstring template, and workflow for adding new aliases live at [`docs/aliases.md`](docs/aliases.md).
+
+### The rule
+
+When writing or refactoring a docstring:
+
+1. If a `@param` / `@tparam` / `@return` line you're about to write would repeat **≥ 5 times** across the codebase, use an existing alias from `docs/links/h5cpp.txt` — or add a new one there and reference it via `\name`.
+2. The chained-aliases line goes at the **end** of the comment, after any `\code` block. Order: `\par_*` → `\tpar_*` → `\returns_*` → `\sa_*`.
+3. New aliases land in the same commit as their first use. Update `docs/aliases.md` so the catalog stays in sync.
+
+The canonical example is `h5cpp/H5Dread.hpp`. The standard template is in [`docs/aliases.md`](docs/aliases.md).