improved NeXus docu.
This commit is contained in:
9
src/external/nexus/Usage.md
vendored
9
src/external/nexus/Usage.md
vendored
@@ -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
|
||||
|
||||
10
src/external/nexus/examples/hdf4/docu/README.md
vendored
10
src/external/nexus/examples/hdf4/docu/README.md
vendored
@@ -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:
|
||||
|
||||
215
src/external/nexus/examples/hdf5/docu/README.md
vendored
215
src/external/nexus/examples/hdf5/docu/README.md
vendored
@@ -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<T>` - 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<T>` - 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/)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user