Add complete ReadTheDocs documentation with Sphinx

Co-authored-by: djw8605 <[email protected]>

Author: Copilot

.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/_build/doxygen/xml/Doxyfile.xml

@@ -0,0 +1,15 @@
+<!-- XSLT script to combine the generated output into a single file. 
+     If you have xsltproc you could use:
+     xsltproc combine.xslt index.xml >all.xml
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+  <xsl:output method="xml" version="1.0" indent="no" standalone="yes" />
+  <xsl:template match="/">
+    <doxygen version="{doxygenindex/@version}" xml:lang="{doxygenindex/@xml:lang}">
+      <!-- Load all doxygen generated xml files -->
+      <xsl:for-each select="doxygenindex/compound">
+        <xsl:copy-of select="document( concat( @refid, '.xml' ) )/doxygen/*" />
+      </xsl:for-each>
+    </doxygen>
+  </xsl:template>
+</xsl:stylesheet>