From d70fd343453ba79726767335d1284e1834af4a7a Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Sun, 8 Feb 2026 09:11:36 +0100 Subject: [PATCH] improved NeXus docu. --- src/external/nexus/Usage.md | 9 + .../nexus/examples/hdf4/docu/README.md | 10 - .../nexus/examples/hdf5/docu/README.md | 215 +++--------------- .../nexus/examples/hdf5/docu/Usage.md | 1 - 4 files changed, 45 insertions(+), 190 deletions(-) diff --git a/src/external/nexus/Usage.md b/src/external/nexus/Usage.md index 8b422d1b..577480f2 100644 --- a/src/external/nexus/Usage.md +++ b/src/external/nexus/Usage.md @@ -99,6 +99,15 @@ switch (type) { | `HDF5` | HDF5 format | `0x89 'H' 'D' 'F' 0x0d 0x0a 0x1a 0x0a` | | `Unknown` | Unrecognized format | - | +### Timestamp Utility + +Generate an ISO 8601 local timestamp string: + +```cpp +std::string timestamp = nxs::getIso8601TimestampLocal(); +// Returns e.g. "2026-02-08T14:30:00" +``` + --- ## Reading NeXus Files diff --git a/src/external/nexus/examples/hdf4/docu/README.md b/src/external/nexus/examples/hdf4/docu/README.md index 1ba03d95..e38315a5 100644 --- a/src/external/nexus/examples/hdf4/docu/README.md +++ b/src/external/nexus/examples/hdf4/docu/README.md @@ -136,16 +136,6 @@ Code migration typically requires only: - `H4DataType::INT8` - 8-bit signed integer - `H4DataType::UINT8` - 8-bit unsigned integer -## Documentation - -Generate Doxygen documentation (if Doxygen is installed): - -```bash -make doc -``` - -Documentation will be generated in the `doc/html` directory. - ## Differences from HDF5 HDF4 has some limitations compared to HDF5: diff --git a/src/external/nexus/examples/hdf5/docu/README.md b/src/external/nexus/examples/hdf5/docu/README.md index 04bf616b..337f7690 100644 --- a/src/external/nexus/examples/hdf5/docu/README.md +++ b/src/external/nexus/examples/hdf5/docu/README.md @@ -5,194 +5,51 @@ This directory contains documentation for the h5nexus project. ## Available Documentation - **Usage.md** - Comprehensive usage guide with detailed examples and workflow patterns -- **mainpage.md** - Main page for Doxygen-generated API documentation -## Generating API Documentation +## Project Structure -The project uses [Doxygen](https://www.doxygen.nl/) to generate comprehensive API documentation from source code comments. +The h5nexus example project has the following structure: + +``` +h5nexus/ +├── CMakeLists.txt - Build configuration +├── main.cpp - Main program source +├── git_revision.sh - Git revision header generator +├── cmake/ +│ ├── config.h.in - CMake config template +│ └── git-revision.h.in - Git revision template +└── docu/ + ├── README.md - This file + └── Usage.md - Detailed usage documentation +``` + +## Building + +```bash +mkdir build +cd build +cmake .. +make +``` ### Prerequisites -- **Doxygen** (required) - Install with: - ```bash - # macOS - brew install doxygen +- CMake >= 3.26 +- C++17 compatible compiler +- HDF5 C++ library +- ROOT >= 6.36 with Minuit2 - # Ubuntu/Debian - sudo apt-get install doxygen +## Key Classes - # Fedora/RHEL - sudo dnf install doxygen - ``` +The h5nexus example uses the PNeXus library which provides: -- **Graphviz** (optional, recommended) - For generating diagrams: - ```bash - # macOS - brew install graphviz - - # Ubuntu/Debian - sudo apt-get install graphviz - - # Fedora/RHEL - sudo dnf install graphviz - ``` - -### Method 1: Using CMake (Recommended) - -If you've already configured your build with CMake: - -```bash -cd build -make doc -``` - -This will generate HTML documentation in the `doc/html/` directory. - -### Method 2: Using Doxygen Directly - -From the project root directory: - -```bash -doxygen Doxyfile -``` - -This will also generate HTML documentation in the `doc/html/` directory. - -## Viewing the Documentation - -After generation, open the main documentation page in your web browser: - -```bash -# macOS -open doc/html/index.html - -# Linux -xdg-open doc/html/index.html - -# Or manually navigate to: file:///path/to/h5nexus/doc/html/index.html -``` - -## Documentation Structure - -The generated documentation includes: - -- **Main Page** - Overview, quick start guide, and architecture description -- **Classes** - Detailed documentation for all classes: - - `nxH5::PNeXus` - Main NeXus file reader/writer class - - `nxH5::PNXdata` - Template class for dataset storage - - `nxH5::PNeXusDeadTime` - Dead time correction calculator -- **Files** - Source file documentation -- **Namespaces** - Namespace documentation (nxH5) -- **Examples** - Code examples from the documentation -- **Class Hierarchy** - Visual class inheritance diagrams -- **Call Graphs** - Function call graphs (if Graphviz is available) -- **Include Dependency Graphs** - Header file dependency visualization - -## Documentation Features - -The Doxygen configuration includes: - -- **Full source browsing** - Browse annotated source code -- **Search functionality** - Fast search across all documentation -- **Interactive SVG diagrams** - Zoomable class and call graphs -- **Cross-references** - Links between related classes and functions -- **Syntax highlighting** - Colored code examples -- **Responsive layout** - Works on desktop and mobile browsers - -## Configuration - -The Doxygen configuration is stored in `Doxyfile` at the project root. Key settings: - -- **Input files**: `inc/`, `src/`, `docu/mainpage.md` -- **Output directory**: `doc/` -- **Output format**: HTML (LaTeX disabled) -- **Graphs**: Enabled if Graphviz/dot is available -- **Extract all**: Yes (documents all code, not just documented items) -- **Source browser**: Enabled - -## Updating Documentation - -To update the documentation after code changes: - -1. Edit Doxygen comments in header/source files -2. Regenerate documentation: `make doc` or `doxygen Doxyfile` -3. Refresh your browser to see changes - -### Doxygen Comment Style - -The project uses Javadoc-style comments: - -```cpp -/** - * @brief Brief description of the function - * - * Detailed description with more information about what - * the function does, how it works, and any important notes. - * - * @param arg1 Description of first parameter - * @param arg2 Description of second parameter - * @return Description of return value - * @throws ExceptionType Description of when this exception is thrown - * - * @note Important note about usage - * @warning Warning about potential issues - * - * @example - * @code - * // Example usage - * MyClass obj; - * obj.myFunction(42, "test"); - * @endcode - */ -void myFunction(int arg1, const std::string& arg2); -``` - -## Cleaning Generated Documentation - -To remove generated documentation: - -```bash -rm -rf doc/html/ -``` - -## Troubleshooting - -### "Doxygen not found" during CMake configuration - -Install Doxygen (see Prerequisites above), then reconfigure: - -```bash -cd build -cmake .. -``` - -### Graphs/diagrams not generating - -Install Graphviz (see Prerequisites above), then regenerate: - -```bash -make doc -# or -doxygen Doxyfile -``` - -### Broken links in documentation - -Ensure all referenced files exist and paths in Doxyfile are correct. The documentation system expects: -- Source files in `inc/` and `src/` -- Main page at `docu/mainpage.md` - -### Documentation looks outdated - -Clear the output directory and regenerate: - -```bash -rm -rf doc/html/ -make doc -``` +- `nxH5::PNeXus` - Main NeXus file reader/writer class +- `nxH5::PNXdata` - Template class for dataset storage +- `nxH5::PNeXusDeadTime` - Dead time correction calculator +- `nxs::checkHDFType()` - File format detection ## Additional Resources - [Doxygen Manual](https://www.doxygen.nl/manual/) -- [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html) -- [Markdown Support in Doxygen](https://www.doxygen.nl/manual/markdown.html) +- [HDF5 Documentation](https://portal.hdfgroup.org/documentation/) +- [NeXus Format](https://www.nexusformat.org/) diff --git a/src/external/nexus/examples/hdf5/docu/Usage.md b/src/external/nexus/examples/hdf5/docu/Usage.md index d1c7629b..a11f9031 100644 --- a/src/external/nexus/examples/hdf5/docu/Usage.md +++ b/src/external/nexus/examples/hdf5/docu/Usage.md @@ -2028,7 +2028,6 @@ Debug output shows: ## Additional Resources -- **PNXdata Usage**: See `PNXdata_usage.md` for detailed PNXdata examples - **HDF5 Documentation**: https://portal.hdfgroup.org/documentation/index.html - **NeXus Format**: https://www.nexusformat.org/ - **ISIS NeXus**: https://www.isis.stfc.ac.uk/Pages/NeXus-Muon-Data.aspx