LMU/musrfit
5
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 4 Activity

improved NeXus docu.

Browse Source
This commit is contained in:
suter_a
2026-02-08 09:11:36 +01:00
parent 3858cc723a
commit d70fd34345
4 changed files with 45 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
src/external/nexus/examples/hdf5/docu/README.md vendored
View File

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