Add comprehensive documentation with examples, cookbooks, and automated deployment

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx_rtd_theme
+          pip install -r requirements.txt
+          pip install .
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Check documentation build
+        run: |
+          if [ ! -d "docs/_build/html" ]; then
+            echo "Documentation build failed!"
+            exit 1
+          fi
+          echo "Documentation built successfully"
+          ls -la docs/_build/html
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html
+          publish_branch: gh-pages
+          force_orphan: true

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+  - epub
+
+# Install Python dependencies required to build your docs
+python:
+  install:
+    - requirements: requirements.txt
+    - method: pip
+      path: .

docs/conf.py

@@ -22,7 +22,7 @@
 author = 'Thomas Stainer'
 
 # The full version, including alpha/beta/rc tags
-release = '1.3.5'
+release = '1.3.8'
 
 
 # -- General configuration ---------------------------------------------------
@@ -31,6 +31,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -47,9 +51,27 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static']
+
+# Theme options
+html_theme_options = {
+    'navigation_depth': 4,
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'includehidden': True,
+    'titles_only': False
+}
+
+# GitHub information
+html_context = {
+    "display_github": True,
+    "github_user": "fispact",
+    "github_repo": "pypact",
+    "github_version": "master",
+    "conf_py_path": "/docs/",
+}