Skip to content

Commit 7b21a08

Browse files
pmadypmady
committed
Adding build developer documentation
Signed-off-by: pmady <pavan4devops@gmail.com>
1 parent 0b3db70 commit 7b21a08

18 files changed

+858
-1
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Documentation build and deployment workflow
2+
# Builds documentation using Doxygen + Sphinx + Breathe
3+
# Deploys to GitHub Pages on pushes to main branch
4+
5+
name: Documentation
6+
7+
on:
8+
push:
9+
branches: [ "main" ]
10+
paths:
11+
- 'docs/**'
12+
- 'include/**'
13+
- '.github/workflows/docs.yml'
14+
pull_request:
15+
paths:
16+
- 'docs/**'
17+
- 'include/**'
18+
- '.github/workflows/docs.yml'
19+
# Allow manual trigger
20+
workflow_dispatch:
21+
22+
permissions:
23+
contents: read
24+
pages: write
25+
id-token: write
26+
27+
# Allow only one concurrent deployment
28+
concurrency:
29+
group: "pages"
30+
cancel-in-progress: true
31+
32+
jobs:
33+
build-docs:
34+
runs-on: ubuntu-latest
35+
36+
steps:
37+
- name: Checkout
38+
uses: actions/checkout@v4
39+
40+
- name: Install Doxygen
41+
run: |
42+
sudo apt-get update
43+
sudo apt-get install -y doxygen
44+
45+
- name: Set up Python
46+
uses: actions/setup-python@v5
47+
with:
48+
python-version: '3.11'
49+
50+
- name: Install Python dependencies
51+
run: |
52+
python -m pip install --upgrade pip
53+
pip install -r docs/requirements.txt
54+
55+
- name: Build Doxygen XML
56+
working-directory: docs
57+
run: doxygen Doxyfile
58+
59+
- name: Build Sphinx HTML
60+
working-directory: docs
61+
run: |
62+
sphinx-build -b html -D breathe_projects.rawtoaces=doxygen/xml . _build/html
63+
64+
- name: Upload artifact for GitHub Pages
65+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
66+
uses: actions/upload-pages-artifact@v3
67+
with:
68+
path: docs/_build/html
69+
70+
deploy-docs:
71+
# Only deploy on push to main
72+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
73+
needs: build-docs
74+
runs-on: ubuntu-latest
75+
76+
environment:
77+
name: github-pages
78+
url: ${{ steps.deployment.outputs.page_url }}
79+
80+
steps:
81+
- name: Deploy to GitHub Pages
82+
id: deployment
83+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,9 @@
22
build/
33
build-coverage/
44
tests/materials/*.exr
5-
__pycache__/
5+
__pycache__/
6+
7+
# Documentation build artifacts
8+
docs/_build/
9+
docs/doxygen/
10+
docs/html/

‎.readthedocs.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Read the Docs configuration file for RAWtoACES
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
4+
version: 2
5+
6+
# Set the OS, Python version, and other tools
7+
build:
8+
os: ubuntu-22.04
9+
tools:
10+
python: "3.11"
11+
apt_packages:
12+
- doxygen
13+
14+
# Build documentation in the "docs/" directory with Sphinx
15+
sphinx:
16+
configuration: docs/conf.py
17+
fail_on_warning: false
18+
19+
# Python requirements for documentation
20+
python:
21+
install:
22+
- requirements: docs/requirements.txt

‎CMakeLists.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,12 @@ endif ( RTA_BUILD_PYTHON_BINDINGS )
105105
enable_testing()
106106
add_subdirectory(tests)
107107

108+
# Documentation (optional)
109+
option( BUILD_DOCS "Build documentation" OFF )
110+
if( BUILD_DOCS )
111+
add_subdirectory(docs)
112+
endif()
113+
108114
#################################################
109115
##
110116
## Install RAWTOACES.pc

‎docs/CMakeLists.txt‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Documentation build configuration for RAWtoACES
2+
#
3+
# This file provides CMake targets for building documentation locally.
4+
# For Read the Docs builds, the documentation is built directly using
5+
# Sphinx and Doxygen without CMake.
6+
7+
find_package(Doxygen)
8+
find_program(SPHINX_EXECUTABLE sphinx-build)
9+
10+
if(DOXYGEN_FOUND AND SPHINX_EXECUTABLE)
11+
message(STATUS "Documentation tools found - enabling 'docs' target")
12+
13+
# Configure Doxyfile with project paths
14+
configure_file(
15+
${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
16+
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
17+
@ONLY
18+
)
19+
20+
# Doxygen target - generates XML for Breathe
21+
add_custom_target(doxygen
22+
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
23+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
24+
COMMENT "Generating API documentation with Doxygen"
25+
VERBATIM
26+
)
27+
28+
# Sphinx target - generates HTML documentation
29+
add_custom_target(sphinx
30+
COMMAND ${SPHINX_EXECUTABLE}
31+
-b html
32+
-c ${CMAKE_CURRENT_SOURCE_DIR}
33+
-D breathe_projects.rawtoaces=${CMAKE_BINARY_DIR}/docs/doxygen/xml
34+
${CMAKE_CURRENT_SOURCE_DIR}
35+
${CMAKE_CURRENT_BINARY_DIR}/html
36+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
37+
COMMENT "Generating HTML documentation with Sphinx"
38+
DEPENDS doxygen
39+
VERBATIM
40+
)
41+
42+
# Main docs target
43+
add_custom_target(docs
44+
DEPENDS sphinx
45+
COMMENT "Building documentation"
46+
)
47+
48+
# Install documentation
49+
install(
50+
DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/
51+
DESTINATION share/doc/rawtoaces
52+
OPTIONAL
53+
COMPONENT documentation
54+
)
55+
56+
else()
57+
if(NOT DOXYGEN_FOUND)
58+
message(STATUS "Doxygen not found - documentation target disabled")
59+
endif()
60+
if(NOT SPHINX_EXECUTABLE)
61+
message(STATUS "Sphinx not found - documentation target disabled")
62+
endif()
63+
endif()

‎docs/Doxyfile‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Doxyfile for RAWtoACES - standalone version for ReadTheDocs
2+
# This file is used when building documentation without CMake
3+
4+
# Project information
5+
PROJECT_NAME = "RAWtoACES"
6+
PROJECT_NUMBER = "2.0.0"
7+
PROJECT_BRIEF = "RAW to ACES Utility"
8+
PROJECT_LOGO =
9+
10+
# Input/Output
11+
INPUT = ../include/rawtoaces
12+
OUTPUT_DIRECTORY = doxygen
13+
RECURSIVE = YES
14+
FILE_PATTERNS = *.h *.hpp
15+
16+
# What to extract
17+
EXTRACT_ALL = YES
18+
EXTRACT_PRIVATE = NO
19+
EXTRACT_STATIC = YES
20+
EXTRACT_LOCAL_CLASSES = YES
21+
22+
# XML output for Breathe
23+
GENERATE_XML = YES
24+
XML_OUTPUT = xml
25+
XML_PROGRAMLISTING = YES
26+
27+
# Disable other outputs (Sphinx/Breathe will handle HTML)
28+
GENERATE_HTML = NO
29+
GENERATE_LATEX = NO
30+
GENERATE_MAN = NO
31+
GENERATE_RTF = NO
32+
33+
# Preprocessing
34+
ENABLE_PREPROCESSING = YES
35+
MACRO_EXPANSION = YES
36+
EXPAND_ONLY_PREDEF = NO
37+
PREDEFINED =
38+
39+
# Source browsing
40+
SOURCE_BROWSER = YES
41+
INLINE_SOURCES = NO
42+
STRIP_CODE_COMMENTS = YES
43+
REFERENCED_BY_RELATION = YES
44+
REFERENCES_RELATION = YES
45+
46+
# Warnings
47+
QUIET = NO
48+
WARNINGS = YES
49+
WARN_IF_UNDOCUMENTED = YES
50+
WARN_IF_DOC_ERROR = YES
51+
WARN_NO_PARAMDOC = YES
52+
53+
# Graphs (disabled for faster builds)
54+
HAVE_DOT = NO
55+
CLASS_DIAGRAMS = NO
56+
57+
# Sorting
58+
SORT_MEMBER_DOCS = YES
59+
SORT_BRIEF_DOCS = YES
60+
SORT_MEMBERS_CTORS_1ST = YES
61+
62+
# Namespaces
63+
HIDE_UNDOC_RELATIONS = NO
64+
SHOW_INCLUDE_FILES = YES
65+
SHOW_GROUPED_MEMB_INC = NO

‎docs/Doxyfile.in‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Doxyfile for RAWtoACES
2+
# This file is configured by CMake to set project-specific paths
3+
4+
# Project information
5+
PROJECT_NAME = "RAWtoACES"
6+
PROJECT_NUMBER = @RAWTOACES_VERSION@
7+
PROJECT_BRIEF = "RAW to ACES Utility"
8+
PROJECT_LOGO =
9+
10+
# Input/Output
11+
INPUT = @CMAKE_SOURCE_DIR@/include/rawtoaces
12+
OUTPUT_DIRECTORY = @CMAKE_BINARY_DIR@/docs/doxygen
13+
RECURSIVE = YES
14+
FILE_PATTERNS = *.h *.hpp
15+
16+
# What to extract
17+
EXTRACT_ALL = YES
18+
EXTRACT_PRIVATE = NO
19+
EXTRACT_STATIC = YES
20+
EXTRACT_LOCAL_CLASSES = YES
21+
22+
# XML output for Breathe
23+
GENERATE_XML = YES
24+
XML_OUTPUT = xml
25+
XML_PROGRAMLISTING = YES
26+
27+
# Disable other outputs (Sphinx/Breathe will handle HTML)
28+
GENERATE_HTML = NO
29+
GENERATE_LATEX = NO
30+
GENERATE_MAN = NO
31+
GENERATE_RTF = NO
32+
33+
# Preprocessing
34+
ENABLE_PREPROCESSING = YES
35+
MACRO_EXPANSION = YES
36+
EXPAND_ONLY_PREDEF = NO
37+
PREDEFINED =
38+
39+
# Source browsing
40+
SOURCE_BROWSER = YES
41+
INLINE_SOURCES = NO
42+
STRIP_CODE_COMMENTS = YES
43+
REFERENCED_BY_RELATION = YES
44+
REFERENCES_RELATION = YES
45+
46+
# Warnings
47+
QUIET = NO
48+
WARNINGS = YES
49+
WARN_IF_UNDOCUMENTED = YES
50+
WARN_IF_DOC_ERROR = YES
51+
WARN_NO_PARAMDOC = YES
52+
53+
# Graphs (disabled for faster builds, enable if needed)
54+
HAVE_DOT = NO
55+
CLASS_DIAGRAMS = NO
56+
57+
# Sorting
58+
SORT_MEMBER_DOCS = YES
59+
SORT_BRIEF_DOCS = YES
60+
SORT_MEMBERS_CTORS_1ST = YES
61+
62+
# Namespaces
63+
HIDE_UNDOC_RELATIONS = NO
64+
SHOW_INCLUDE_FILES = YES
65+
SHOW_GROUPED_MEMB_INC = NO

‎docs/_static/.gitkeep‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# This file ensures the _static directory is tracked by git

0 commit comments

Comments
 (0)