[#282]:svarga:docs, flatten reports tree + curated I/O+TOPICS axis + top-level REPORTS nav + v1.12.6 accuracy pass

Reorganises the Doxygen documentation tree into a 4-axis structure
(I/O / TOPICS / COOKBOOK / USABILITY) with REPORTS as a fifth top-level
tab, and reconciles every architecture / inventory / taxonomy report
against h5cpp v1.12.6's actual implementation state.

Layout (doxy/DoxygenLayout.xml):
  - I/O axis: FILE (h5::create, h5::open) / DATASET / ATTRIBUTES / GROUPS
  - TOPICS axis: PROPERTIES / LINEAR ALGEBRA / STL / REFLECTION / FILTERS /
    MPI / ERROR / TYPESYSTEM / CDASH (no longer carries REPORTS as a child)
  - COOKBOOK: 28 example READMEs unchanged
  - USABILITY: top-level link at reports_usability_evaluation
  - REPORTS: new top-level tab, links to reports_index

Reports tree flattened (docs/reports/{architecture,compatibility,inventories,
project,surveys,taxonomies}/ -> docs/reports/). 15 files renamed via git
rename detection; the 6 subdirectory index.md files removed. New
docs/reports/index.md groups the 18 reports thematically: Architecture &
Design / Inventories & Guides / Compiler Attribute Taxonomies / Surveys
& Comparisons / Project Assessment.

Doxyfile (doxy/Doxyfile):
  - USE_MDFILE_AS_MAINPAGE: ../README.md -> ../docs/index.md
  - INPUT: drop ../README.md, add ../docs/index.md + ../docs/curated
  - EXCLUDE_SYMBOLS: add h5::impl::*, h5::error::*, h5::pod, h5::strlen,
    h5::has_scatter, h5::gorilla, h5::uniform, h5::normal, h5::exponential,
    h5::bernoulli — keeps the error-leaf hierarchy out of the nav tree

Curated tree (docs/curated/) — new:
  - io-api/{index,file,dataset,attributes,groups}.md + io-api/file/{create,open}.md
  - topics/{index,properties,linalg,stl,reflection,filters,mpi,error,
    typesystem,cdash,architecture}.md
  - Reflection page carries the fully-decorated [[h5::*]] worked example
    + the generated H5T_COMPOUND / scatter / gather code expansion

Front page (docs/index.md): purpose-built Doxygen landing distinct from
README.md — hero pitch + 10-line snippet, comparison table vs direct
HDF5 in C/C++, 3-axis nav, capability matrix, single combined install
table with H5CPP + COMPILER columns and reference-style links, project
status with badges, acknowledgements, project info.

v1.12.6 accuracy pass — reviewed and updated against actual code:
  - h5cpp-type-system-map.md: complex<T> gate is HDF5 >= 2.0 (not 1.16);
    enum support qualified as H5CPP_REGISTER_DATATYPE-only; compiler
    attribute list reduced to what h5cpp-compiler actually parses
    ([[h5::alias]] and [[h5::version]] removed — not implemented today).
    Fixed smart-quote-inside-backtick rendering bug in section 16
    (was breaking the entire Unsupported-by-design table).
  - h5cpp-type-system-architecture-notes.md: reframed from "prototype
    working-tree bank as of 2026-05-26" to "v1.12.6 (released)";
    storage_representation enum extended with Winston-model additions
    (array_element / array_dataset / fls_dataset / fixed_length_string);
    "current bank" / "current session" temporal markers replaced.
  - h5cpp-handle-inventory.md: "14 property-list variants" -> 16;
    async typedef range 353-359 -> 353-358; "remaining 8" -> 10;
    ROS3 build break documented as resolved via H5FD_CURR_ROS3_FAPL_T_VERSION
    gate.
  - h5cpp-compiler-multi-backend-architecture.md: rewritten — was
    speculative ("tier-2 on AI roadmap"), now reflects 11 backends
    shipped (hdf5/protobuf/json/msgpack/cbor/bson/avro/rlp/sql ×3
    dialects). Attribute namespaces corrected to flat top-level
    ([[pb::*]] / [[json::*]] / etc, NOT nested h5::proto::* / h5::json::*).
    CMake helper documented as supporting hdf5 | protocol-buffers only.
  - h5cpp-threaded-pipeline-sigma-queue-design.md: superseded-status
    banner — actual implementation shipped as pool_pipeline_t with
    std::future + std::async (no sigma queue dependency).
  - h5cpp-usability-evaluation.md: 84 yellow stars + 21 white stars
    replaced with monochrome ●/○ scorecard; complex<T> field names
    {re,im} -> {r,i}; enum class and opaque types corrected from
    not-supported to supported-via-H5CPP_REGISTER_DATATYPE.

New report: h5cpp-multithreading-pipeline-state.md — current state of
the filter pipeline at v1.12.6, covering both the h5::high_throughput
DAPL path and the h5::append packet-table path through pt_t. Documents
the three orthogonal pieces (FAPL worker pool / DAPL flag /
pool_pipeline_t), the cross-path behaviour matrix, back-pressure policy,
honest limitations list, and a profiling recipe.

[#282]:svarga:docs, retire MkDocs — drop config, top-level pages, theme dirs, build/CI targets; Doxygen publishes to gh-pages root

Removes the MkDocs configuration and all Material-theme remnants now
that the Doxygen tree (front page + I/O + TOPICS + COOKBOOK + USABILITY +
REPORTS, with the curated reports tree) is the single documentation source.

Top-level config:
  - mkdocs.yml

docs/ top-level Markdown pages (none referenced from docs/index.md or
the Doxygen INPUT list):
  - architecture.md + architecture-{core,io,types,integration,parallelism}.md
  - compiler.md, cpp-standard-compliance-report.md, design.md
  - examples.md, filtering-pipeline-rework-report.md
  - s3.md, stl.md, thirdparty.md, workflow.md

docs/ subdirs (mkdocs/Material only — confirmed not in Doxyfile INPUT):
  - overrides/  (Material custom_dir, 6 files)
  - assets/     (Material assets, 12 files)
  - styles/     (MkDocs CSS, 8 files)
  - javascripts/ (MkDocs JS, 8 files)
  - icons/      (Material icons, 22 files)
  - dot/        (2 files — Doxygen has its own DOT integration)
  - skills/     (7 .md files)
  - examples/   (5 .md files — Doxygen EXCLUDEs this dir)

Kept (all currently consumed by Doxygen):
  - docs/index.md           — USE_MDFILE_AS_MAINPAGE target
  - docs/aliases.md         — INPUT-listed alias-vocabulary page
  - docs/curated/           — I/O + TOPICS tree
  - docs/reports/           — flat reports tree
  - docs/links/             — Doxyfile @INCLUDE_PATH
  - docs/tags/              — Doxyfile TAGFILES (cppreference cross-refs)
  - docs/pix/               — Doxyfile IMAGE_PATH
  - docs/doxygen/           — build output

CMakeLists.txt: drop find_program(MKDOCS_EXECUTABLE) block + the
'docs' (mkdocs build) and 'docs-serve' (mkdocs serve --livereload)
custom targets. docs-doxygen target preserved.

.github/workflows/docs.yml: drop the entire deploy-mkdocs job (Python
setup, pip install mkdocs+material, mkdocs build, deploy ./site).
The remaining deploy-doxygen job now publishes to the gh-pages
root (destination_dir removed) instead of /api, so the Doxygen site
takes over the URL that MkDocs used to serve.

Net diff: 88 files / -15,593 / +6.  Local rebuild via scripts/docs-build.sh
is clean (0 warnings); every key landing page still resolves
(curated_io_api, curated_topics, reports_index, USABILITY, REPORTS).

[#282]:svarga:docs, drop docs/pix/ (unreferenced) + tidy Doxyfile IMAGE_PATH + EXCLUDE

The docs/pix/ tree carried 14 image files (gifs / pngs / svgs / a jpg
or two) from the MkDocs era — financial_eng.jpg, steve-varga.jpg,
perf-{armadillo,stl,struct}.png, sparse-csr.svg, julia-sparse-mat.png,
matrix-base.svg, meta.svg, two other.svg variants, FF-IH_File{Group,Object}.gif,
c-strings-inmemory.png.

Verified unreferenced before removal:
  - 0 markdown `![](pix/...)` image links anywhere in docs/
  - 0 Doxygen `@image` / `\image` directives in source
  - 0 references from kept-input files (docs/index.md, docs/aliases.md,
    docs/curated/, docs/reports/, h5cpp/, examples/, doxy/)
  - 0 images copied into the rendered docs/doxygen/html/ output by
    the previous build

Doxyfile tidied alongside:
  - IMAGE_PATH = ../docs/pix      → removed (target no longer exists)
  - EXCLUDE list trimmed to just  `../docs/doxygen` — the seven mkdocs-era
    EXCLUDE entries (overrides / assets / styles / javascripts / dot /
    icons / pix / examples) all pointed at directories that were deleted
    in the MkDocs retirement commit and are dead config.

Local rebuild via scripts/docs-build.sh is clean (0 warnings); every
key landing page still resolves.

[#282]:svarga:docs, move docs/ tree under doxy/ — single Doxygen project root, doxy/docs/ holds all sources + build output

Consolidates everything Doxygen-related under doxy/. The top-level
docs/ directory is gone; its contents move as a single subtree to
doxy/docs/ so the Doxygen project (config + theme + sources + build
output) lives in one place.

Moved (git-rename detected, content unchanged — 44 files):
  docs/index.md           → doxy/docs/index.md          (Doxygen mainpage)
  docs/aliases.md         → doxy/docs/aliases.md        (Doxygen INPUT alias page)
  docs/curated/   (18)    → doxy/docs/curated/          (I/O + TOPICS axes)
  docs/reports/   (19)    → doxy/docs/reports/          (project reports tree)
  docs/links/     (4)     → doxy/docs/links/            (Doxyfile @INCLUDE_PATH)
  docs/tags/      (1)     → doxy/docs/tags/             (cppreference TAGFILE)

Build output (untracked, .gitignored — not in the rename set):
  docs/doxygen/   (490+ generated files)   → doxy/docs/doxygen/

Path updates (4 modifications):

  doxy/Doxyfile — all `../docs/X` references rewritten to `docs/X`
  (Doxyfile sits in doxy/ and docs/ is now its sibling):
    OUTPUT_DIRECTORY, WARN_LOGFILE, INPUT, EXCLUDE, USE_MDFILE_AS_MAINPAGE,
    TAGFILES, @INCLUDE_PATH

  scripts/docs-build.sh — post-process target + final message updated
  to doxy/docs/doxygen/html

  .github/workflows/docs.yml — three path references:
    log=docs/doxygen/warnings.log     → doxy/docs/doxygen/warnings.log
    path: docs/doxygen/warnings.log   → doxy/docs/doxygen/warnings.log
    publish_dir: ./docs/doxygen/html  → ./doxy/docs/doxygen/html

  .gitignore — updated for new build path; dropped two mkdocs-era stale
  lines:
    docs/docs/site                    → removed
    site/                             → removed
    docs/doxygen/                     → doxy/docs/doxygen/

Side benefit: the `../../../examples/X` cross-references in some
reports (h5cpp-handle-inventory.md, h5cpp-filters-inventory-and-use-guide.md)
were broken after the earlier reports-tree flattening — they assumed
3-level depth. Reports now live 3 levels deep again (doxy/docs/reports/X.md),
so the existing paths resolve correctly without further editing.

Local rebuild via scripts/docs-build.sh is clean (0 warnings); every
key landing page resolves at doxy/docs/doxygen/html/. The development
server is restarted against the new path.

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:
@@ -55,13 +33,13 @@ jobs:
           # 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)
+      - name: Build Doxygen documentation (version from git tag, post-processed)
         run: scripts/docs-build.sh
 
       - name: Summarise Doxygen warnings
         if: always()
         run: |
-          log=docs/doxygen/warnings.log
+          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')"
@@ -75,14 +53,13 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: doxygen-warnings
-          path: docs/doxygen/warnings.log
+          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,6 +158,4 @@ data/
 # =============================================================================
 # Documentation build output
 # =============================================================================
-docs/docs/site
-site/
-docs/doxygen/
+doxy/docs/doxygen/

CMakeLists.txt

@@ -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