[#282]:svarga:docs, Doxygen API reference site + alias vocabulary + content tree

Closes #282. Stand up the full h5cpp API reference site under
docs/doxygen/, served from the alias-first docstring vocabulary
defined in docs/links/*.txt and catalogued in docs/aliases.md.

ALIAS VOCABULARY

* docs/aliases.md — publishable catalog with 6 tables (parameters,
  template params, returns, see-also bundles, function-group headers)
  plus the standard docstring template, workflow for adding/removing
  aliases (>= 5-use threshold), and the alias-first contribution rule
  also added to CONTRIBUTING.md.
* docs/links/h5cpp.txt — par_*, tpar_*, returns_*, func_*_hdr.
  v1.12.6 surface adds: par_mdspan, par_sparse, par_ref_t, sa_async,
  sa_sparse, sa_mdspan, sa_token. par_args (dataset I/O) and the
  new par_args_attr (attribute I/O, no chunking, no partial I/O)
  document the variadic surface.
* docs/links/hdf5.txt / stl.txt / linalg.txt — sa_hdf5 / sa_stl /
  sa_linalg bundles rewritten as inline markdown links because
  Doxygen substitutes \n as <br/> not real newline, breaking the
  earlier markdown reference-style ([name][] + [name]: URL) pairing.

ALIAS ADOPTION SWEEP

* H5Dwrite.hpp — 73 inline @param/@return blocks replaced with
  aliases.
* H5Dcreate.hpp — 14 inline blocks replaced.
* H5Dgather.hpp / H5Dranges.hpp / H5Sall.hpp — smaller surfaces.
* H5Eall.hpp — 48 exception structs decorated with one-line
  @brief docstrings; each leaf type now produces a standalone
  Doxygen struct reference page (84 total reference pages).
* H5config.hpp — @defgroup attribute-io added so the
  \func_attr_hdr alias renders a Group page (companion to the
  existing io-create, io-read, io-write, io-append, file-io,
  io-wrap groups).

CONTENT PAGES (doxy/anchors.dox)

* Error Handling — full hierarchy table, CHECK_* macros,
  mute/unmute, rollback discipline, all 48 exception types.
* Conversion Policy — 6 sections covering default/explicit/refcount/
  async/inventory/use_cases; cross-references the Handle Reference
  page where the conversion mechanism lives.
* Handles, Descriptors, and Property Lists — consolidated reference
  with 6 categorised tables (object handles, async, references,
  property lists [16 entries], shape descriptors, implementation).
* Supported Types — comprehensive 13-section catalog (elementary
  scalars, strings, compound, arrays, STL sequence/associative/
  array-of, ragged, linalg dense, linalg sparse, mdspan, references,
  smart pointers, NOT supported) each row mapping the type to its
  storage_representation_t value.
* Supported Linear Algebra Types — sparse storage layout, dense
  storage layout, overview table, then per-library deep dives for
  Armadillo, Eigen, Blaze, Blitz++, dlib, IT++, Boost uBLAS,
  xtensor; mixing rules; dispatch traits.
* Tightened older stubs (link_stl_template_types,
  link_linalg_template_types) into focused redirects pointing at
  the comprehensive Supported Types catalog.

COOK BOOK + REPORTS TREE

* 28 example READMEs wired into Doxygen as @page subpages under
  the master examples_guides_index. Top-level "Examples" tab
  hidden (visible="no" in DoxygenLayout.xml) because the cook
  book navigation already exposes them.
* Tone pass on examples/container/README.md (and the example-guide
  master) to a neutral / technical voice.
* docs/reports/ scaffolded into 4 categories — architecture (12),
  taxonomies/surveys (8), inventories & guides (5), compatibility &
  projects (8) — wired into Doxyfile INPUT.

RENDERING + SIGNATURE PIPELINE

* Doxygen function signatures: compact rendering via customdoxygen.css
  (collapse <table class="memname"> to inline flow); postprocess
  step in scripts/docs-postprocess.sh tightens whitespace
  (trailing space in memname cell, " &amp;" / " *" inside paramtype,
  " ," in template parameter lists).
* MACRO_EXPANSION + EXPAND_AS_DEFINED in doxy/Doxyfile so SFINAE
  return-type macros (e.g. H5CPP_ATTR_CREATE_RET) collapse to the
  advertised return type in the rendered signature without leaking
  std::enable_if_t<...> into the headline. Gated on the
  H5CPP_DOXYGEN sentinel.
* cppreference URLs canonicalised in docs-postprocess.sh:
  http://...w/... → https://... and trailing .html stripped
  (~1631 URLs rewritten per build).
* HDF5 doc URLs rewritten to support.hdfgroup.org/documentation/
  hdf5/latest/.
* aliases.md table rendering fix: rewording the Conventions list
  to avoid \func_*_hdr and @InGroup mentions even inside backticks
  (Doxygen markdown table parser is fragile to those tokens).
* Version pipeline: scripts/docs-build.sh derives the project
  version from CMakeLists.txt H5CPP_PROJECT_VERSION as
  source-of-truth; git tag override only when HEAD sits on a clean
  v<n>.<n>.<n> release tag.
* CSS: --content-maxwidth raised to 1600px (over-broad rules from
  an earlier attempt that broke the doxygen-awesome flex layout
  were reverted).
* Doxygen footer: "Generated by" credit and logo removed; only
  copyright remains.
* @verbatim wrap on aliases.md docstring examples to suppress
  alias substitution inside the code samples.

CI + BUILD

* .github/workflows/docs.yml uploads Doxygen WARN_LOGFILE as a
  build artifact for coverage tracking.
* .gitignore drops generated docs/doxygen/ output.

Author: steven-varga

.github/workflows/docs.yml

@@ -45,8 +45,39 @@ 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 API reference (version from git tag, post-processed)
+        run: scripts/docs-build.sh
+
+      - name: Summarise Doxygen warnings
+        if: always()
+        run: |
+          log=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: docs/doxygen/warnings.log
+          if-no-files-found: ignore
+          retention-days: 30
 
       - name: Deploy Doxygen to gh-pages/api
         uses: peaceiris/actions-gh-pages@v4

.gitignore

@@ -159,4 +159,5 @@ data/
 # Documentation build output
 # =============================================================================
 docs/docs/site
-site/
+site/
+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]*"

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).

docs/aliases.md

@@ -0,0 +1,170 @@
+@page aliases_reference Doxygen alias vocabulary
+
+H5CPP uses a controlled vocabulary of Doxygen aliases so that repeated `@param` / `@tparam` / `@return` / `@see` fragments are defined **once** in `docs/links/*.txt` and referenced everywhere with a `\name` token.
+
+One source of truth. A wording change in one file propagates automatically to every overload that uses the alias.
+
+Use this page as the developer reference when writing or refactoring docstrings, and as the project reference for what each `\alias` token in the generated API site means.
+
+
+
+## How the mechanism works
+
+The Doxyfile pulls in four alias-definition files via `@INCLUDE_PATH` and `@INCLUDE`:
+
+| File | Purpose |
+|---|---|
+| `docs/links/h5cpp.txt` | the core h5cpp alias set — parameters, returns, see-also bundles, function-group headers |
+| `docs/links/hdf5.txt` | HDF5 C-API cross-reference bundles |
+| `docs/links/linalg.txt` | Armadillo / Eigen / Blitz / Blaze / dlib / uBLAS cross-reference bundles |
+| `docs/links/stl.txt` | `std::vector` / `std::array` / `std::string` / `std::mdspan` cross-reference bundles |
+
+When Doxygen processes a docstring, every `\name` token is expanded inline into the alias's full text. A docstring carrying
+
+```text
+\\par_file_path \\par_dataset_path \\par_offset \\par_stride \\par_count \\par_block \\par_dxpl \\tpar_T \\returns_object \\sa_h5cpp \\sa_stl
+```
+
+(double-backslash here is a display artefact so this guide can show the syntax literally — write a single `\` in your actual docstrings.) Expands into eleven fully-formed `@param` / `@tparam` / `@return` / `@see` blocks at API-reference generation time.
+
+
+
+## Standard docstring template
+
+The canonical shape of an h5cpp API docstring:
+
+```text
+/** \\func_read_hdr
+ *  One-line summary of what this overload does.
+ *
+ *  Optional 2–3 sentences elaborating function-specific content. Keep prose
+ *  to what's unique about this overload — boilerplate (param descriptions,
+ *  return types, exception semantics) comes from aliases.
+ *
+ *  Embedded example block goes here using Doxygen's code / endcode pair.
+ *
+ *  \\par_file_path \\par_dataset_path \\par_offset \\par_stride \\par_count \\par_block \\par_dxpl \\tpar_T \\returns_object
+ *  \\sa_h5cpp \\sa_stl
+ */
+```
+
+(Double-backslashes in the template above are a display artefact — write a single `\` in your actual docstrings.)
+
+Conventions:
+
+- The chained-aliases line goes at the **end** of the comment, after any code block.
+- One line if it fits in ~120 columns; otherwise one alias per line.
+- Order: `par_*` (in declaration order) then `tpar_*` then `returns_*` then `sa_*` aliases.
+- The `func_*_hdr` family (one per overload group) goes on the **first** line of the comment.
+
+
+
+## Vocabulary catalog
+
+### Parameters
+
+| Alias | Expands to (summary) |
+|---|---|
+| `\par_file_path` | `@param file_path` — path to the HDF5 container in the OS file system |
+| `\par_dataset_path` | `@param dataset_path` — POSIX-style path within the container |
+| `\par_attr` | `@param attr` — UTF-8 attribute name (relative to parent object) |
+| `\par_fcrt_flags` | `@param flags` — `H5F_ACC_TRUNC` / `EXCL` / `DEBUG` |
+| `\par_fopn_flags` | `@param flags` — `H5F_ACC_RDWR` / `RDONLY` |
+| `\par_fd` | `@param fd` — open `h5::fd_t` file descriptor |
+| `\par_ds` | `@param ds` — open `h5::ds_t` dataset descriptor |
+| `\par_sp` | `@param sp` — valid `h5::sp_t` dataspace descriptor |
+| `\par_handle` | `@param handle` — any `h5::hid_t<T>` descriptor (`fd_t` / `ds_t` / `gr_t` / `at_t` / `dcpl_t` / `fapl_t`) |
+| `\par_ref_t` | `@param ref` — valid `h5::reference_t` handle (RAII) |
+| `\par_fcpl` | `@param fcpl` — file creation property list |
+| `\par_fapl` | `@param fapl` — file access property list (driver, parallel I/O) |
+| `\par_dapl` | `@param dapl` — dataset access property list |
+| `\par_dcpl` | `@param dcpl` — dataset creation property list |
+| `\par_dxpl` | `@param dxpl` — data transfer property list |
+| `\par_lcpl` | `@param lcpl` — link creation property list |
+| `\par_ref` | `@param ref` — linalg object or `std::vector<T>` |
+| `\par_ptr` | `@param ptr` — caller memory region |
+| `\par_offset` | `@param offset` — first-element coordinates in file space |
+| `\par_stride` | `@param stride` — step between selected elements |
+| `\par_count` | `@param count` — blocks per dimension |
+| `\par_block` | `@param block` — block size per dimension |
+| `\par_max_dims` | `@param max_dims` — max extent; `H5S_UNLIMITED` for extendable |
+| `\par_current_dims` | `@param current_dims` — initial extent |
+| `\par_chunk_dims` | `@param chunk` — chunked-storage chunk shape |
+| `\par_deflate` | `@param deflate` — gzip level 0–9 |
+| `\par_thread_count` | `@param N` — FAPL worker-pool size (0 disables) |
+| `\par_args` | `@param args[, ...]` — variadic context-sensitive optionals for dataset I/O (offset / stride / count / block / dxpl / current_dims / max_dims / dcpl / lcpl …) |
+| `\par_args_attr` | `@param args[, ...]` — variadic context-sensitive optionals for attribute I/O (`h5::current_dims`, `h5::acpl_t`); offset / stride / count / block / dxpl / max_dims / dcpl / lcpl do **not** apply (no chunking, no partial I/O) |
+| `\par_mdspan` | `@param view` — `std::mdspan` over caller storage |
+| `\par_sparse` | `@param matrix` — `arma::SpMat` / `Eigen::SparseMatrix` (CSC layout) |
+
+### Template parameters
+
+| Alias | Expands to |
+|---|---|
+| `\tpar_T` | `@tparam T` — supported elementary type, registered compound, or linalg object |
+| `\tpar_FD` | `@tparam fd_t` — `hid_t` or `h5::fd_t` |
+| `\tpar_DS` | `@tparam ds_t` — `hid_t` or `h5::ds_t` |
+| `\tpar_AP` | `@tparam fcpl_t` — `h5::fcpl_t` / `hid_t` / `H5P_DEFAULT` |
+| `\tpar_CP` | `@tparam fapl_t` — `h5::fapl_t` / `hid_t` / `H5P_DEFAULT` |
+
+### Returns
+
+| Alias | Expands to |
+|---|---|
+| `\returns_fd` | `@return` — open `h5::fd_t`; throws `h5::error` |
+| `\returns_ds` | `@return` — open `h5::ds_t`; throws `h5::error` |
+| `\returns_err` | `@return` — `void`; errors via `h5::error` exceptions |
+| `\returns_object` | `@return` — fully-constructed object of type `T` |
+| `\returns_string_vec` | `@return` — `std::vector<std::string>` |
+| `\returns_gr` | `@return` — `h5::gr_t` for on-disk group layout |
+| `\returns_ref` | `@return` — `h5::reference_t` handle |
+| `\returns_paths` | `@return` — `std::vector<std::string>` of object paths |
+
+### See-also bundles
+
+| Alias | Expands to |
+|---|---|
+| `\sa_h5cpp` | h5cpp entry points: `open` / `read` / `write` / `fd_t` / `ds_t` / `err_t` |
+| `\sa_exception` | `@exception std::runtime_error if the dataset or file is not found` |
+| `\sa_conversion` | h5cpp ↔ HDF5 implicit conversion explainer |
+| `\sa_hdf5` | HDF5 C-API cross-references (defined in `docs/links/hdf5.txt`) |
+| `\sa_linalg` | linalg-library cross-references (defined in `docs/links/linalg.txt`) |
+| `\sa_stl` | STL cross-references (defined in `docs/links/stl.txt`) |
+| `\sa_sparse` | sparse-CSC API cluster + scipy/Julia/10x interop notes |
+| `\sa_mdspan` | C++23 `std::mdspan` + libstdc++/libc++ version floors |
+| `\sa_async` | FAPL-scoped async executor model |
+| `\sa_token` | HDF5 1.12+ token-based identity (`token_t`, `oinfo`, `token_equal`) |
+
+### Function-group headers
+
+| Alias | Expands to | Use on |
+|---|---|---|
+| `\func_read_hdr` | `@ingroup io-read` | every `h5::read` overload |
+| `\func_write_hdr` | `@ingroup io-write` | every `h5::write` overload |
+| `\func_create_hdr` | `@ingroup io-create` | every `h5::create` overload |
+| `\func_attr_hdr` | `@ingroup attribute-io` | every `h5::aread` / `h5::awrite` |
+| `\func_sparse_hdr` | `@ingroup sparse-io` | sparse read/write overloads |
+| `\func_async_hdr` | `@ingroup async-io` | `h5::async::*` factories |
+| `\func_traversal_hdr` | `@ingroup traversal` | `h5::ls` / `h5::dfs` / `h5::bfs` |
+| `\func_read_desc` | one-line read description | combine with `func_read_hdr` |
+| `\func_write_desc` | one-line write description | combine with `func_write_hdr` |
+| `\func_create_links` | a `\sa_*` bundle for create | use after `func_create_hdr` |
+
+
+
+## Adding a new alias
+
+1. Confirm it'll appear **≥ 5 times** across the API. If not, write the `@param` inline.
+2. Open `docs/links/h5cpp.txt` (or `hdf5.txt` / `linalg.txt` / `stl.txt` if cross-domain).
+3. Add the alias under the matching section header (e.g. `############ FILE / DATASET PARAMETERS`).
+4. Use the alias at one call site to validate the expansion.
+5. Run `cd doxy && doxygen Doxyfile` locally; confirm the generated HTML renders the substituted text correctly.
+6. Add an entry to this page (`docs/aliases.md`) so the catalog stays in sync.
+
+
+
+## Removing an alias
+
+If an alias has zero callers and offers nothing the existing vocabulary can't express, drop it. Same rule applies if an alias is renamed or replaced — the old name doesn't linger. The deletion goes through `docs/links/*.txt` (and removes the row from this page).
+
+If callers exist, migrate them in the same commit as the removal.