Merge branch 'staging' into release

Author: steven varga

.github/workflows/ci.yml

@@ -845,8 +845,14 @@ jobs:
             '*/test/*' \
             '*/thirdparty/*' \
             '*/examples/*' \
+            '*/h5cpp/H5Zpipeline_pool.hpp' \
             --ignore-errors unused,mismatch,inconsistent \
             --output-file coverage.info
+          # H5Zpipeline_pool.hpp is excluded TEMPORARILY: the FAPL worker pool
+          # never reaches the write/read dispatch (H5Fget_access_plist drops the
+          # inserted property), so pool_pipeline_t is unreachable through the
+          # public API and reads as 0% dead code. Tracked in #286 — remove this
+          # exclusion once activation is fixed and the pool path is exercised.
 
           rm coverage.full.info
           lcov --gcov-tool /usr/bin/gcov-14 --list coverage.info

.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]*"
@@ -226,6 +226,30 @@ if(MSVC)
     target_compile_options(h5cpp INTERFACE /Zc:__cplusplus)
 endif()
 
+# The h5cpp-compiler reflection annotations ([[h5::doc]], [[h5::chunk]],
+# [[h5::compress]], [[h5::name]], [[h5::ignore]], ...) live in the `h5::`
+# attribute namespace. A plain compiler — i.e. one not running the h5cpp-compiler
+# preprocessing pass — does not know that namespace, ignores the attributes, and
+# emits -Wattributes for every annotated struct. Declare the namespace
+# intentional so consumers that annotate their own types build cleanly. Scoped
+# to `h5::` where the compiler supports it (GCC 11+); Clang/older GCC fall back
+# to the broader unknown-attribute switch; MSVC silences C5030.  Guarded by
+# check_cxx_compiler_flag so unsupported toolchains are left untouched. (#291)
+if(MSVC)
+    target_compile_options(h5cpp INTERFACE /wd5030)
+else()
+    include(CheckCXXCompilerFlag)
+    check_cxx_compiler_flag("-Wno-attributes=h5::" H5CPP_HAS_WNO_ATTRIBUTES_NS)
+    if(H5CPP_HAS_WNO_ATTRIBUTES_NS)
+        target_compile_options(h5cpp INTERFACE -Wno-attributes=h5::)
+    else()
+        check_cxx_compiler_flag("-Wno-unknown-attributes" H5CPP_HAS_WNO_UNKNOWN_ATTRIBUTES)
+        if(H5CPP_HAS_WNO_UNKNOWN_ATTRIBUTES)
+            target_compile_options(h5cpp INTERFACE -Wno-unknown-attributes)
+        endif()
+    endif()
+endif()
+
 if(H5CPP_HAVE_ROS3_VFD)
     target_compile_definitions(h5cpp INTERFACE H5CPP_HAVE_ROS3_VFD=1)
 endif()
@@ -453,25 +477,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).

CTestCustom.cmake

@@ -2,3 +2,20 @@ set(CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE 1048576)
 set(CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE 1048576)
 set(CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS 100)
 set(CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS 100)
+
+# Coverage scope — restrict the CDash Coverage step to the h5cpp library
+# headers only.  Without these excludes CTest folds every instrumented
+# .gcda it can find into the dashboard, so vendored thirdparty libraries,
+# the test harness, and the example translation units inflate the LOC
+# denominator and bury the real library figure (observed: 9276 LOC counted
+# vs. 2453 library lines).  These patterns are POSIX regexes matched against
+# the absolute source path and mirror the lcov --remove list in the CI
+# coverage job (ci.yml) so CDash and Codecov report the same number.
+set(CTEST_CUSTOM_COVERAGE_EXCLUDE
+    ${CTEST_CUSTOM_COVERAGE_EXCLUDE}
+    "/thirdparty/"
+    "/test/"
+    "/examples/"
+    "/usr/"
+    "/CMakeFiles/"
+)