Add comprehensive ReadTheDocs documentation with Sphinx and C++ API integration plus GitHub workflow testing

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+
+name: Documentation Build Test
+
+on:
+  push:
+    branches:
+      - '**'
+    tags:
+      - '*'
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    name: Build Documentation
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: recursive
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y doxygen
+
+    - name: Install Python dependencies
+      run: |
+        pip install -r docs/requirements.txt
+
+    - name: Build documentation
+      working-directory: docs
+      run: |
+        make html
+
+    - name: Upload artifact for GitHub Pages
+      if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') || github.event_name == 'release'
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs/_build/html
+
+  deploy-docs:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') || github.event_name == 'release'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -1 +1,4 @@
 build
+
+# Documentation build artifacts
+docs/_build/

.readthedocs.yml

@@ -0,0 +1,18 @@
+# ReadTheDocs Configuration File
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  apt_packages:
+    - doxygen
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

Doxyfile

@@ -0,0 +1,51 @@
+# Doxyfile configuration for SciTokens C++ library
+
+# Project related configuration options
+PROJECT_NAME           = "SciTokens C++"
+PROJECT_NUMBER         = "1.0.2"
+PROJECT_BRIEF          = "A C++ Library to interface to scitokens"
+OUTPUT_DIRECTORY       = docs/_build/doxygen
+
+# Build related configuration options
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = NO
+
+# Configuration options related to the input files
+INPUT                  = src/scitokens.h
+FILE_PATTERNS          = *.h *.hpp *.cpp
+RECURSIVE              = NO
+EXCLUDE_PATTERNS       = */vendor/* */build/* */_build/*
+
+# Configuration options related to source browsing
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+
+# Configuration options related to the alphabetical class index
+ALPHABETICAL_INDEX     = YES
+
+# Configuration options related to the HTML output
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+
+# Configuration options related to the preprocessor
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = src/
+PREDEFINED             = __cplusplus
+
+# Configuration options related to external references
+TAGFILES               =
+GENERATE_TAGFILE       =
+
+# Configuration options related to the dot tool
+HAVE_DOT               = NO
+
+# Configuration options related to the search engine
+SEARCHENGINE           = NO

docs/Makefile

@@ -0,0 +1,20 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= 
+SPHINXBUILD  ?= sphinx-build
+SOURCEDIR    = .
+BUILDDIR     = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,60 @@
+# SciTokens C++ Documentation
+
+This directory contains the Sphinx documentation for the SciTokens C++ library.
+
+## Building the Documentation
+
+### Prerequisites
+
+1. Install Python dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Install Doxygen (for API extraction):
+   ```bash
+   # Ubuntu/Debian
+   sudo apt install doxygen
+
+   # CentOS/RHEL
+   sudo yum install doxygen
+   ```
+
+### Building
+
+From this directory, run:
+
+```bash
+make html
+```
+
+Or using sphinx-build directly:
+
+```bash
+sphinx-build -b html . _build/html
+```
+
+The generated documentation will be in `_build/html/`.
+
+## Documentation Structure
+
+- `index.rst` - Main documentation page
+- `installation.rst` - Installation and building instructions
+- `api.rst` - API reference (auto-generated from source comments)
+- `examples.rst` - Usage examples
+- `conf.py` - Sphinx configuration
+- `requirements.txt` - Python dependencies
+
+## ReadTheDocs Integration
+
+This documentation is configured for ReadTheDocs. See `.readthedocs.yml` in the project root for the configuration.
+
+The documentation will automatically build when pushed to the repository.
+
+## Adding Examples
+
+Examples in `examples.rst` are based on the test cases in the `test/` directory. When adding new functionality, please:
+
+1. Add appropriate docstring comments to the public API functions in `src/scitokens.h`
+2. Add usage examples to `examples.rst`
+3. Test that the documentation builds without warnings

docs/api.rst

@@ -0,0 +1,8 @@
+API Reference
+=============
+
+This page provides the complete API reference for the SciTokens C++ library. 
+The API is primarily exposed as a C interface for maximum compatibility.
+
+.. doxygenfile:: scitokens.h
+   :project: scitokens-cpp

docs/conf.py

@@ -0,0 +1,53 @@
+# Configuration file for the Sphinx documentation builder.
+# 
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'SciTokens C++'
+copyright = '2024, SciTokens Team'
+author = 'SciTokens Team'
+release = '1.0.2'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'breathe',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output ------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- Breathe Configuration --------------------------------------------------
+
+breathe_projects = {
+    "scitokens-cpp": "_build/doxygen/xml"
+}
+breathe_default_project = "scitokens-cpp"
+
+# -- Doxygen integration ----------------------------------------------------
+
+import subprocess
+import os
+
+def run_doxygen(app, config):
+    """Run doxygen to generate XML for breathe"""
+    try:
+        subprocess.run(['doxygen', 'Doxyfile'], cwd='..', check=True)
+    except subprocess.CalledProcessError:
+        print("Failed to run doxygen")
+
+def setup(app):
+    app.connect('config-inited', run_doxygen)