Adding build developer documentation

.github/workflows/docs.yml

@@ -0,0 +1,83 @@
+# Documentation build and deployment workflow
+# Builds documentation using Doxygen + Sphinx + Breathe
+# Deploys to GitHub Pages on pushes to main branch
+
+name: Documentation
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'docs/**'
+      - 'include/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'include/**'
+      - '.github/workflows/docs.yml'
+  # Allow manual trigger
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Doxygen
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build Doxygen XML
+        working-directory: docs
+        run: doxygen Doxyfile
+
+      - name: Build Sphinx HTML
+        working-directory: docs
+        run: |
+          sphinx-build -b html -D breathe_projects.rawtoaces=doxygen/xml . _build/html
+
+      - name: Upload artifact for GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy-docs:
+    # Only deploy on push to main
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build-docs
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -2,4 +2,9 @@
 build/
 build-coverage/
 tests/materials/*.exr
-__pycache__/
+__pycache__/
+
+# Documentation build artifacts
+docs/_build/
+docs/doxygen/
+docs/html/

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file for RAWtoACES
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version, and other tools
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  apt_packages:
+    - doxygen
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# Python requirements for documentation
+python:
+  install:
+    - requirements: docs/requirements.txt

CMakeLists.txt

@@ -105,6 +105,12 @@ endif ( RTA_BUILD_PYTHON_BINDINGS )
 enable_testing()
 add_subdirectory(tests)
 
+# Documentation (optional)
+option( BUILD_DOCS "Build documentation" OFF )
+if( BUILD_DOCS )
+    add_subdirectory(docs)
+endif()
+
 #################################################
 ##
 ##   Install RAWTOACES.pc

docs/CMakeLists.txt

@@ -0,0 +1,63 @@
+# Documentation build configuration for RAWtoACES
+#
+# This file provides CMake targets for building documentation locally.
+# For Read the Docs builds, the documentation is built directly using
+# Sphinx and Doxygen without CMake.
+
+find_package(Doxygen)
+find_program(SPHINX_EXECUTABLE sphinx-build)
+
+if(DOXYGEN_FOUND AND SPHINX_EXECUTABLE)
+    message(STATUS "Documentation tools found - enabling 'docs' target")
+
+    # Configure Doxyfile with project paths
+    configure_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+        ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+        @ONLY
+    )
+
+    # Doxygen target - generates XML for Breathe
+    add_custom_target(doxygen
+        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM
+    )
+
+    # Sphinx target - generates HTML documentation
+    add_custom_target(sphinx
+        COMMAND ${SPHINX_EXECUTABLE}
+            -b html
+            -c ${CMAKE_CURRENT_SOURCE_DIR}
+            -D breathe_projects.rawtoaces=${CMAKE_BINARY_DIR}/docs/doxygen/xml
+            ${CMAKE_CURRENT_SOURCE_DIR}
+            ${CMAKE_CURRENT_BINARY_DIR}/html
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        COMMENT "Generating HTML documentation with Sphinx"
+        DEPENDS doxygen
+        VERBATIM
+    )
+
+    # Main docs target
+    add_custom_target(docs
+        DEPENDS sphinx
+        COMMENT "Building documentation"
+    )
+
+    # Install documentation
+    install(
+        DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/
+        DESTINATION share/doc/rawtoaces
+        OPTIONAL
+        COMPONENT documentation
+    )
+
+else()
+    if(NOT DOXYGEN_FOUND)
+        message(STATUS "Doxygen not found - documentation target disabled")
+    endif()
+    if(NOT SPHINX_EXECUTABLE)
+        message(STATUS "Sphinx not found - documentation target disabled")
+    endif()
+endif()

docs/Doxyfile

@@ -0,0 +1,65 @@
+# Doxyfile for RAWtoACES - standalone version for ReadTheDocs
+# This file is used when building documentation without CMake
+
+# Project information
+PROJECT_NAME           = "RAWtoACES"
+PROJECT_NUMBER         = "2.0.0"
+PROJECT_BRIEF          = "RAW to ACES Utility"
+PROJECT_LOGO           =
+
+# Input/Output
+INPUT                  = ../include/rawtoaces
+OUTPUT_DIRECTORY       = doxygen
+RECURSIVE              = YES
+FILE_PATTERNS          = *.h *.hpp
+
+# What to extract
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+
+# XML output for Breathe
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+
+# Disable other outputs (Sphinx/Breathe will handle HTML)
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_MAN           = NO
+GENERATE_RTF           = NO
+
+# Preprocessing
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+PREDEFINED             =
+
+# Source browsing
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+
+# Warnings
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+
+# Graphs (disabled for faster builds)
+HAVE_DOT               = NO
+CLASS_DIAGRAMS         = NO
+
+# Sorting
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = YES
+SORT_MEMBERS_CTORS_1ST = YES
+
+# Namespaces
+HIDE_UNDOC_RELATIONS   = NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO

docs/Doxyfile.in

@@ -0,0 +1,65 @@
+# Doxyfile for RAWtoACES
+# This file is configured by CMake to set project-specific paths
+
+# Project information
+PROJECT_NAME           = "RAWtoACES"
+PROJECT_NUMBER         = @RAWTOACES_VERSION@
+PROJECT_BRIEF          = "RAW to ACES Utility"
+PROJECT_LOGO           =
+
+# Input/Output
+INPUT                  = @CMAKE_SOURCE_DIR@/include/rawtoaces
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs/doxygen
+RECURSIVE              = YES
+FILE_PATTERNS          = *.h *.hpp
+
+# What to extract
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+
+# XML output for Breathe
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+
+# Disable other outputs (Sphinx/Breathe will handle HTML)
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_MAN           = NO
+GENERATE_RTF           = NO
+
+# Preprocessing
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+PREDEFINED             =
+
+# Source browsing
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+
+# Warnings
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+
+# Graphs (disabled for faster builds, enable if needed)
+HAVE_DOT               = NO
+CLASS_DIAGRAMS         = NO
+
+# Sorting
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = YES
+SORT_MEMBERS_CTORS_1ST = YES
+
+# Namespaces
+HIDE_UNDOC_RELATIONS   = NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO

docs/_static/.gitkeep

@@ -0,0 +1 @@
+# This file ensures the _static directory is tracked by git