From aab31795bff883d07ed0681aab0d301978f87522 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 10 Nov 2025 00:15:53 +0000
Subject: [PATCH] Fix ReadTheDocs API documentation generation

- Remove :noindex: directive from pystackql.rst to allow Sphinx to generate API docs
- Add :special-members: directive to include __init__ documentation
- Configure autodoc with proper default options in conf.py
- Add sphinx.ext.napoleon extension for better docstring parsing
- Create .readthedocs.yaml configuration file for proper RTD builds
- Install package during build to enable autodoc to import and document the module

This fixes the issue where StackQL class properties and methods were not being documented on ReadTheDocs.
---
 .readthedocs.yaml         | 22 ++++++++++++++++++++++
 docs/source/conf.py       | 26 ++++++++++++++++++++++++++
 docs/source/pystackql.rst |  2 +-
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 .readthedocs.yaml

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..39a5da7
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt
diff --git a/docs/source/conf.py b/docs/source/conf.py
index f2c1d9a..472b4e5 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -42,8 +42,34 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
+    'sphinx.ext.napoleon',
 ]
 
+# Autodoc configuration
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+
+# Napoleon settings for Google/NumPy style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../_templates']
 
diff --git a/docs/source/pystackql.rst b/docs/source/pystackql.rst
index b6c9b5f..890d389 100644
--- a/docs/source/pystackql.rst
+++ b/docs/source/pystackql.rst
@@ -4,9 +4,9 @@ API Reference for pystackql
 StackQL Class
 -------------
 .. autoclass:: pystackql.StackQL
-    :noindex:
     :members:
     :undoc-members:
     :show-inheritance:
+    :special-members: __init__