[#2]:svarga:docs, added initial readme-s

Author: steven-varga

README.md

@@ -1,16 +1,36 @@
-<!---
- Copyright (c) 2018-2020 Steven Varga, Toronto,ON Canada
- Author: Varga, Steven <steven@vargaconsulting.ca>
---->
 
-Source code transformation tool for HDF5 dataformat  H5CPP header only library  
-----------------------------------------------------------------------------------------------------
+[![CI](https://github.com/vargaconsulting/h5cpp-compiler/actions/workflows/ci.yml/badge.svg)](https://github.com/vargaconsulting/h5cpp-compiler/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/vargaconsulting/h5cpp-compiler/branch/main/graph/badge.svg)](https://codecov.io/gh/vargaconsulting/h5cpp-compiler)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17069343.svg)](https://doi.org/10.5281/zenodo.17069343)
+
+[![GitHub release](https://img.shields.io/github/v/release/vargaconsulting/h5cpp-compiler.svg)](https://github.com/vargaconsulting/h5cpp-compiler/releases)
+[![Documentation](https://img.shields.io/badge/docs-stable-blue)](https://vargaconsulting.github.io/h5cpp-compiler)
+
+# Source code transformation tool for HDF5 dataformat  H5CPP header only library  
+## Build Matrix
+
+| OS / Compiler | GCC 13      | GCC 14      | GCC 15      | Clang 14      | Clang 15      | Clang 17      |
+|---------------|-------------|-------------|-------------|---------------|---------------|---------------|
+| Ubuntu 22.04  |![gcc13][200]|![gcc14][201]|![gcc15][202]|![clang14][210]|![clang15][211]|![clang17][212]|
+| Ubuntu 24.04  |![gcc13][300]|![gcc14][301]|![gcc15][302]|![clang14][310]|![clang15][311]|![clang17][312]|
+| macOS         |![gcc13][600]|![gcc14][601]|![gcc15][602]|![clang14][610]|![clang15][611]|![clang17][612]|
+| Windows       |![gcc13][700]|![gcc13][701]|![gcc13][702]|![clang14][710]|![clang15][711]|![clang17][712]|
+
 
 This source code transformation tool simplifies the otherwise time consuming process of generating the shim code for HDF5 Compound datatypes by building the AST of a given TU translation unit, and identifying all POD datatypes referenced from H5CPP operators/functions.
 The result is a seamless persistence much similar to python, java or other reflection based languages. 
 
 The following excerpt shows the mechanism, how `vec` variable is marked by `h5::write` operator. When `h5cpp` tool is invoked it builds the full AST of the translation unit, finds the referenced types, then in topological order generates HDF5 COMPOUND datatype descriptors. The generated file has include guards, and meant to be used with [H5CPP template library](h5cpp.org). POD struct types may be arbitrary deep, embedded in POD C like arrays, and may be referenced from STL containers. Currently `stl::vector` is supported, but in time full support will be provided.
 
+## Installation
+```bash
+sudo apt install build-essential cmake
+cmake -DCMAKE_BUILD_TYPE=Release -S . -B build
+cmake --build build --parallel
+sudo cmake --install build
+```
+
 ```cpp
 ...
 std::vector<sn::example::Record> vec 
@@ -68,64 +88,57 @@ namespace sn {
 	/* END IGNORED STRUCTS */
 ```
 
-Install:
-----------
-Only **LLVM 6.0 is supported**, to compile from  source you need both the llvm and clang-dev package installed:
-```
-sudo apt install llvm-6.0 llvm-6.0-dev libclang-6.0-dev  # 640MB space needed
-make && make install                                     # compile the source code transforation tool
-```
-optionally you can remove the development libraries, and install only the runtime
+
+# Python virtual environment for this website
+
+## Setup
+
+```bash
+python3 -m venv .venv                 # Create a virtual env (Python 3.10+ recommended)
+source .venv/bin/activate             # Activate: Linux / macOS
+# On Windows use: .venv\Scripts\activate
+
+pip install --upgrade pip             # Upgrade pip
+pip install mkdocs-material           # Install MkDocs + Material theme
+pip install python-frontmatter jinja2 python-dateutil pyyaml  # Extra deps
 ```
-sudo apt purge llvm-6.0 libllvm-6.0-dev libclang-6.0-dev # remove development libraries
-sudo apt install libllvm6.0 libclang-common-6.0-dev      # install runtime dependencies
+
+## Run MkDocs locally
+
+```bash
+source .venv/bin/activate
+mkdocs serve --dev-addr=127.0.0.1:9000   # Live preview at http://127.0.0.1:9000
+mkdocs build -v                          # Build static site locally
 ```
 
-Caveat:
--------
-All LLVM version other than 6.0 is failing, or crashing including the clang++ chain. This is being investigated, and once resolved this message
-will be removed.
-
-Usage:
--------
-`h5cpp  your_translation_unit.cpp -- -v $(CXXFLAGS)  -Dgenerated.h`
-will run the compiler front end on the specified input, and outputs the necessary HDF5 type descriptors, or 
-the error message if any.
-
-
-
-[hdf5]: https://support.hdfgroup.org/HDF5/doc/H5.intro.html
-[1]: http://en.cppreference.com/w/cpp/container/vector
-[2]: http://arma.sourceforge.net
-[4]: https://support.hdfgroup.org/HDF5/doc/RM/RM_H5Front.html
-[5]: https://support.hdfgroup.org/HDF5/release/obtain5.html
-[6]: http://eigen.tuxfamily.org/index.php?title=Main_Page
-[7]: http://www.boost.org/doc/libs/1_65_1/libs/numeric/ublas/doc/matrix.htm
-[8]: https://julialang.org/
-[9]: https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_.28CSR.2C_CRS_or_Yale_format.29
-[10]: https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_column_.28CSC_or_CCS.29
-[11]: https://en.wikipedia.org/wiki/List_of_numerical_libraries#C++
-[12]: http://en.cppreference.com/w/cpp/concept/StandardLayoutType
-[40]: https://support.hdfgroup.org/HDF5/Tutor/HDF5Intro.pdf
-[99]: https://en.wikipedia.org/wiki/C_(programming_language)#Pointers
-[100]: http://arma.sourceforge.net/
-[101]: http://www.boost.org/doc/libs/1_66_0/libs/numeric/ublas/doc/index.html
-[102]: http://eigen.tuxfamily.org/index.php?title=Main_Page#Documentation
-[103]: https://sourceforge.net/projects/blitz/
-[104]: https://sourceforge.net/projects/itpp/
-[105]: http://dlib.net/linear_algebra.html
-[106]: https://bitbucket.org/blaze-lib/blaze
-[107]: https://github.com/wichtounet/etl
-[200]: http://h5cpp.org/md__home_steven_Documents_projects_h5cpp_profiling_README.html
-[201]: http://h5cpp.org/examples.html
-[202]: http://h5cpp.org/modules.html
-[305]: md__home_steven_Documents_projects_h5cpp_docs_pages_compiler_trial.html#link_try_compiler
-[400]: https://www.meetup.com/Chicago-C-CPP-Users-Group/events/250655716/
-[401]: https://www.hdfgroup.org/2018/07/cpp-has-come-a-long-way-and-theres-plenty-in-it-for-users-of-hdf5/
-[999]: http://h5cpp.org/cgi/redirect.py
-[301]: http://h5cpp.org/md__home_steven_Documents_projects_h5cpp_docs_pages_conversion.html
-[302]: http://h5cpp.org/md__home_steven_Documents_projects_h5cpp_docs_pages_exceptions.html
-[303]: http://h5cpp.org/md__home_steven_Documents_projects_h5cpp_docs_pages_compiler.html
-[304]: http://h5cpp.org/md__home_steven_Documents_projects_h5cpp_docs_pages_linalg.html
-[305]: http://h5cpp.org/md__home_steven_Documents_projects_h5cpp_docs_pages_install.html
-[400]: http://h5cpp.org/md__home_steven_Documents_projects_h5cpp_docs_pages_error_handling.html
+<!-- Ubuntu 22.04 -->
+[200]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-gcc-13.svg
+[201]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-gcc-14.svg
+[202]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-gcc-15.svg
+[210]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-clang-14.svg
+[211]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-clang-15.svg
+[212]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-clang-17.svg
+
+<!-- Ubuntu 24.04 -->
+[300]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-gcc-13.svg
+[301]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-gcc-14.svg
+[302]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-gcc-15.svg
+[310]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-clang-14.svg
+[311]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-clang-15.svg
+[312]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-clang-17.svg
+
+<!-- macOS latest -->
+[600]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-gcc-13.svg
+[601]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-gcc-14.svg
+[602]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-gcc-15.svg
+[610]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-clang-14.svg
+[611]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-clang-15.svg
+[612]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-clang-17.svg
+
+<!-- Windows (clang & gcc) -->
+[700]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-gcc-13.svg
+[701]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-gcc-14.svg
+[702]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-gcc-15.svg
+[710]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-clang-14.svg
+[711]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-clang-15.svg
+[712]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-clang-17.svg

docs/index.md

@@ -0,0 +1,126 @@
+---
+hide:
+  - toc
+---
+
+<div class="flex flex-wrap gap-2">
+  <a href="https://github.com/vargaconsulting/h5cpp-compiler/actions">
+    <img src="https://img.shields.io/badge/CI-passing-brightgreen" class="h-6" />
+  </a>
+  <a href="https://codecov.io/gh/vargaconsulting/h5cpp-compiler">
+    <img src="https://img.shields.io/codecov/c/github/vargaconsulting/h5cpp-compiler" class="h-6" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-green.svg" class="h-6" />
+  </a>
+  <a href="https://doi.org/10.5281/zenodo.17069343">
+    <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.17069343.svg" class="h-6" />
+  </a>
+</div>
+
+
+| OS / Compiler | GCC 13      | GCC 14      | GCC 15      | Clang 14      | Clang 15      | Clang 17      |
+|---------------|-------------|-------------|-------------|---------------|---------------|---------------|
+| Ubuntu 22.04  |![gcc13][200]|![gcc14][201]|![gcc15][202]|![clang14][210]|![clang15][211]|![clang17][212]|
+| Ubuntu 24.04  |![gcc13][300]|![gcc14][301]|![gcc15][302]|![clang14][310]|![clang15][311]|![clang17][312]|
+| macOS         |![gcc13][600]|![gcc14][601]|![gcc15][602]|![clang14][610]|![clang15][611]|![clang17][612]|
+| Windows       |![gcc13][700]|![gcc13][701]|![gcc13][702]|![clang14][710]|![clang15][711]|![clang17][712]|
+
+H5CPP compiler is an LLVM/Clang–powered **reverse schema compiler**. Instead of forcing you to design schemas up front, the H5CPP compiler dives into your existing C and C++ code, extracts full type graphs, and automatically generates persistence descriptors. Born out of the [H5CPP header-only library](http://h5cpp.org), the compiler eliminates the grind of hand-crafting shim code for HDF5 compound datatypes. Mark a variable with a persistence operator (like `h5::write`), and the H5CPP compiler will walk the AST, discover every dependent type, and in clean topological order emit a ready-to-use header with HDF5 descriptors. Self-contained, include-guarded, and built to drop straight into your workflow.  
+
+The payoff? **Non-intrusive, reflection-driven persistence for modern C and C++** — the ease of Python or Java–style serialization, but with the raw performance, type safety, and zero-overhead ethos that C and C++ demand. Complex POD structs? Deeply nested arrays? STL containers? No problem. The H5CPP compiler handles them with ease. Today it supports `std::vector`, tomorrow an ever-growing slice of the STL universe.  
+
+```cpp
+std::vector<sn::example::Record> vec 
+    = h5::utils::get_test_data<sn::example::Record>(20);
+
+// mark vec with an h5:: operator and delegate 
+// the details to h5cpp compiler
+h5::write(fd, "orm/partial/vector one_shot", vec );
+````
+
+### Example Structs
+
+```cpp
+namespace sn {
+    namespace typecheck {
+        struct Record {
+            char  _char; unsigned char _uchar; short _short; unsigned short _ushort;
+            int _int; unsigned int _uint; long _long; unsigned long _ulong;
+            long long int _llong; unsigned long long _ullong;
+            float _float; double _double; long double _ldouble;
+            bool _bool;
+            // wide characters are not supported in HDF5
+            // wchar_t _wchar; char16_t _wchar16; char32_t _wchar32;
+        };
+    }
+
+    namespace other {
+        struct Record {
+            MyUInt idx;
+            MyUInt aa;
+            double field_02[3];
+            typecheck::Record field_03[4];
+        };
+    }
+
+    namespace example {
+        struct Record {
+            MyUInt idx;
+            float field_02[7];
+            sn::other::Record field_03[5];
+            sn::other::Record field_04[5]; // optimized out, same as previous
+            other::Record field_05[3][8];  // array of arrays
+        };
+    }
+
+    namespace not_supported_yet {
+        // NON POD: not supported in phase 1
+        struct Container {
+            double idx;
+            std::string field_05;                  // non-POD
+            std::vector<example::Record> field_02; // non-POD
+        };
+    }
+
+    /* BEGIN IGNORED STRUCT */
+    // These structs are not referenced with h5::read|h5::write|h5::create
+    struct IgnoredRecord {
+        signed long int idx;
+        float field_0n;
+    };
+    /* END IGNORED STRUCT */
+}
+```
+
+<!-- Ubuntu 22.04 -->
+[200]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-gcc-13.svg
+[201]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-gcc-14.svg
+[202]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-gcc-15.svg
+[210]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-clang-14.svg
+[211]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-clang-15.svg
+[212]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-22.04-clang-17.svg
+
+<!-- Ubuntu 24.04 -->
+[300]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-gcc-13.svg
+[301]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-gcc-14.svg
+[302]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-gcc-15.svg
+[310]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-clang-14.svg
+[311]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-clang-15.svg
+[312]: https://vargaconsulting.github.io/h5cpp-compiler/badges/ubuntu-24.04-clang-17.svg
+
+<!-- macOS latest -->
+[600]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-gcc-13.svg
+[601]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-gcc-14.svg
+[602]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-gcc-15.svg
+[610]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-clang-14.svg
+[611]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-clang-15.svg
+[612]: https://vargaconsulting.github.io/h5cpp-compiler/badges/macos-latest-clang-17.svg
+
+<!-- Windows (clang & gcc) -->
+[700]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-gcc-13.svg
+[701]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-gcc-14.svg
+[702]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-gcc-15.svg
+[710]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-clang-14.svg
+[711]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-clang-15.svg
+[712]: https://vargaconsulting.github.io/h5cpp-compiler/badges/windows-latest-clang-17.svg