Add documentation

.github/dependabot.yml

@@ -4,6 +4,14 @@ version: 2
 # pull request when a newer release of an action referenced there appears, which
 # runs the build workflow and therefore gets tested on every runner before it is
 # merged.
+#
+# Two more package-ecosystem entries below cover the Python side: the pyproject.toml
+# dependencies (numpy/scipy, plus the test/docs extras and the nanobind/scikit-build-core
+# build backend) and docs/requirements.txt, which is a separate tree on purpose -- see
+# the comment there -- so Dependabot needs to be pointed at it explicitly.
+#
+# Not covered, because Dependabot has no ecosystem for it: the openlibm FetchContent pin
+# (GIT_TAG v0.8.7) in CMakeLists.txt. That one has to be bumped by hand.
 
 updates:
   - package-ecosystem: github-actions
@@ -27,3 +35,43 @@ updates:
         update-types:
           - minor
           - patch
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/Berlin
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: deps
+    labels:
+      - dependencies
+      - python
+    groups:
+      python-minor:
+        applies-to: version-updates
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: pip
+    directory: /docs
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/Berlin
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: docs
+    labels:
+      - dependencies
+      - docs
+    groups:
+      docs-minor:
+        applies-to: version-updates
+        update-types:
+          - minor
+          - patch

.github/workflows/build.yml

@@ -359,3 +359,9 @@ jobs:
           name: ompmc-coverage
           path: coverage-html/
           if-no-files-found: error
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.info

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: docs
+
+# Builds the Sphinx/Doxygen/Breathe site the same way Read the Docs does (see
+# .readthedocs.yaml), so a broken build is caught on the PR rather than after
+# it merges. Deliberately does not install the project itself -- the docs
+# build needs no C++ compiler, see the comment in docs/conf.py -- only
+# docs/requirements.txt and the doxygen binary.
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'ucodes/omc_python/**'
+      - 'README.md'
+      - 'BUILDING.md'
+      - 'CMakeLists.txt'
+      - '.readthedocs.yaml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install doxygen
+        run: sudo apt-get update && sudo apt-get install -y doxygen
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements.txt
+
+      # -W turns warnings into errors, -n reports broken cross-references
+      # (a :func:`...` to a symbol that no longer exists, for example), and
+      # --keep-going collects every failure in one run instead of stopping at
+      # the first.
+      - name: Build docs
+        run: sphinx-build -b html -W --keep-going -n docs docs/_build/html
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html

.gitignore

@@ -18,6 +18,11 @@ __pycache__/
 dist/
 .pytest_cache/
 
+# Sphinx/Doxygen documentation build
+docs/_build/
+docs/doxygen/
+.venv-docs/
+
 # CMake build trees and their products
 build/
 build-*/

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  apt_packages:
+    - doxygen
+  commands:
+    # `build.commands` replaces RTD's default build entirely, so this does
+    # its own dependency install (docs/requirements.txt, NOT the project --
+    # see the comment there) and its own sphinx-build. -W/-n turn broken
+    # cross-references and undocumented autodoc targets into a failed build,
+    # matching .github/workflows/docs.yml.
+    - pip install -r docs/requirements.txt
+    - sphinx-build -b html -W --keep-going -n docs $READTHEDOCS_OUTPUT/html

CITATION.cff

@@ -0,0 +1,42 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: ompMC
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Edgardo
+    family-names: Doerner
+    email: endoerner@gmail.com
+    affiliation: Pontificia Universidad Católica de Chile
+  - given-names: Niklas
+    family-names: Wahl
+    email: n.wahl@dkfz-heidelberg.de
+    affiliation: Deutsches Krebsforschungszentrum
+    orcid: 'https://orcid.org/0000-0002-1451-223X'
+repository-code: 'https://github.com/e0404/ompMC'
+repository: 'https://github.com/edoerner/ompMC'
+keywords:
+  - radiotherapy
+  - Monte Carlo
+license: GPL-3.0
+preferred-citation:
+  type: article
+  title: 'Technical Note: An hybrid parallel implementation for EGSnrc Monte Carlo user codes'
+  authors:
+    - given-names: Edgardo
+      family-names: Doerner
+      email: endoerner@gmail.com
+      affiliation: Pontificia Universidad Católica de Chile
+    - given-names: P.
+      family-names: Caprile
+  journal: Medical Physics
+  volume: 45
+  issue: 8
+  start: '3969'
+  end: '3973'
+  year: 2018
+  doi: 10.1002/mp.13033

CMakeLists.txt

@@ -21,7 +21,7 @@
 cmake_minimum_required(VERSION 3.20)
 
 project(ompMC
-    VERSION 0.1.0
+    VERSION 0.2.0
     DESCRIPTION "An OpenMP parallel implementation for Monte Carlo particle transport simulations"
     HOMEPAGE_URL "https://github.com/e0404/ompMC"
     LANGUAGES C)
@@ -733,6 +733,25 @@ if(OMPMC_BUILD_TESTS)
     endif()
 endif()
 
+################################################################################
+# Documentation
+################################################################################
+
+# Convenience target for people who drive everything through CMake; not part
+# of ALL and not needed for Read the Docs, which runs sphinx-build directly
+# (see .readthedocs.yaml) so that building the docs never needs this
+# configure step or a C++ toolchain. See docs/README.md for the equivalent
+# plain sphinx-build command.
+find_program(SPHINX_BUILD_EXECUTABLE sphinx-build)
+if(SPHINX_BUILD_EXECUTABLE)
+    add_custom_target(docs
+        COMMAND "${SPHINX_BUILD_EXECUTABLE}" -b html
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs"
+                "${CMAKE_CURRENT_BINARY_DIR}/docs/html"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMENT "Building Sphinx documentation")
+endif()
+
 ################################################################################
 # Installation
 ################################################################################

README.md

@@ -1,5 +1,18 @@
 # ompMC
 
+[![Build](https://github.com/e0404/ompMC/actions/workflows/build.yml/badge.svg)](https://github.com/e0404/ompMC/actions/workflows/build.yml)
+[![Docs](https://github.com/e0404/ompMC/actions/workflows/docs.yml/badge.svg)](https://github.com/e0404/ompMC/actions/workflows/docs.yml)
+[![codecov](https://codecov.io/gh/e0404/ompMC/branch/master/graph/badge.svg)](https://codecov.io/gh/e0404/ompMC)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
+
+[![C](https://img.shields.io/badge/C-A8B9CC?logo=c&logoColor=white)](src/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+[![MATLAB](https://img.shields.io/badge/MATLAB-0076A8?logo=mathworks&logoColor=white)](ucodes/omc_matrad/)
+
+[![Windows](https://img.shields.io/badge/Windows-0078D6?logo=windows&logoColor=white)](.github/workflows/build.yml)
+[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](.github/workflows/build.yml)
+[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)](.github/workflows/build.yml)
+
 > The original repository is **[edoerner/ompMC](https://github.com/edoerner/ompMC)** by Edgardo Doerner.
 > This repository is a fork under further development, aimed at integration into the
 > treatment planning toolkits **[matRad](https://github.com/e0404/matRad)** (`e0404/matRad`)
@@ -318,4 +331,4 @@ Windows x64 (MSVC and MinGW), Linux x64, Linux ARM64, macOS x64 and macOS ARM64.
 ## License
 
 GNU General Public License v3.0 — see [LICENSE](LICENSE).
-Copyright (C) 2018 Edgardo Doerner (edoerner@fis.puc.cl).
+Copyright (C) 2018-2026 Edgardo Doerner and Niklas Wahl.

docs/Doxyfile

@@ -0,0 +1,60 @@
+# Minimal Doxygen config: XML output only, consumed by Breathe/Sphinx. Runs as
+# a subprocess of docs/conf.py, not part of the CMake build -- see the comment
+# there for why. Any setting not listed here uses Doxygen's built-in default.
+
+PROJECT_NAME           = "ompMC"
+PROJECT_NUMBER         = $(OMPMC_DOXYGEN_VERSION)
+PROJECT_BRIEF          = "OpenMP parallel Monte Carlo photon and electron transport"
+OUTPUT_DIRECTORY       = doxygen
+QUIET                  = YES
+WARN_AS_ERROR          = NO
+
+# Public C API only: the 10 headers a host embeds ompMC through. ompmc.h/.c
+# hold the physics transport internals, meant for maintainers reading the
+# source directly rather than an API reference; see docs/c-api/internals.md.
+INPUT                  = ../src
+FILE_PATTERNS          = *.h
+EXCLUDE                = ../src/ompmc.h
+RECURSIVE              = NO
+
+# The GPL banner opens with /**** rather than /** or /*!, so Doxygen skips it
+# without an EXCLUDE_PATTERNS entry -- see JAVADOC_AUTOBRIEF below.
+JAVADOC_AUTOBRIEF       = YES
+OPTIMIZE_OUTPUT_FOR_C   = YES
+TYPEDEF_HIDES_STRUCT    = NO
+EXTRACT_ALL             = NO
+EXTRACT_STATIC          = NO
+HIDE_UNDOC_MEMBERS      = NO
+HIDE_UNDOC_CLASSES      = NO
+SORT_MEMBER_DOCS        = NO
+MARKDOWN_SUPPORT        = YES
+WARN_IF_UNDOCUMENTED   = YES
+
+# Each header's @file comment mentions the others by plain filename (e.g.
+# "(omc_geom.h)") as prose, not as a link. With autolinking on, Doxygen turns
+# those into cross-file references that only resolve if every referenced
+# file's page happens to already be registered in the same Sphinx build in
+# the right order, which our per-file `doxygenfile` pages spread across three
+# separate c-api/*.md pages do not reliably satisfy -- breaking the build
+# with "undefined label" errors that have nothing to do with a real missing
+# doc. Explicit references (`#name`, `struct Foo`) are unaffected; this only
+# turns off the automatic kind.
+AUTOLINK_SUPPORT        = NO
+
+# omcLog()/omcFail() carry GCC/MSVC attribute macros (noreturn, printf format
+# checking) that Doxygen's C parser copies verbatim into the declaration text
+# it hands Breathe, and Breathe's declaration parser then chokes on them ("not
+# valid C++") since they are not real syntax. Expanding just these two to
+# nothing, rather than turning on full preprocessing, keeps every other macro
+# in the headers (MXMED, MAX_MEDIA-style constants, threadprivate guards)
+# showing up in the docs as written.
+ENABLE_PREPROCESSING    = YES
+MACRO_EXPANSION         = YES
+EXPAND_ONLY_PREDEF      = YES
+PREDEFINED              = OMC_NORETURN= \
+                          OMC_PRINTF_LIKE(fmtArg,firstArg)=
+
+GENERATE_HTML           = NO
+GENERATE_LATEX          = NO
+GENERATE_XML            = YES
+XML_PROGRAMLISTING      = NO

docs/README.md

@@ -0,0 +1,23 @@
+# Building the documentation locally
+
+No C++ compiler needed: the compiled `_ompmc` extension is mocked out (see
+`conf.py`), so this only needs Python, Doxygen, and the packages in
+`requirements.txt`.
+
+```sh
+# Doxygen: apt install doxygen / brew install doxygen / choco install doxygen.strawberry
+python -m venv .venv-docs
+.venv-docs/Scripts/activate        # .venv-docs/bin/activate on Linux/macOS
+pip install -r docs/requirements.txt
+
+sphinx-build -b html docs docs/_build/html
+```
+
+Open `docs/_build/html/index.html`. Rebuild after an edit with the same
+command; add `-E` to force a full rebuild (e.g. after editing `conf.py` or
+`Doxyfile`) or `-W -n --keep-going` to build the way CI does, which turns
+warnings and broken cross-references into a failing build.
+
+`sphinx-autobuild docs docs/_build/html` (from the `sphinx-autobuild`
+package, not in `requirements.txt`) rebuilds and reloads a browser tab on
+every save, useful while editing prose.