From d0e611cd646decd0d23059d1c02b79cce76cb19c Mon Sep 17 00:00:00 2001 From: jsonbailey Date: Tue, 12 May 2026 13:56:38 -0500 Subject: [PATCH] feat: Publish openai provider API reference via RTD subproject Moves the existing server-ai Sphinx docs setup (previously at the repo root) into packages/sdk/server-ai/ so each package's docs live next to its code, and adds an equivalent docs setup for the openai provider package at packages/ai-providers/server-ai-openai/. Two Read the Docs features make this work: - Monorepo support via per-package .readthedocs.yaml files, selected in the RTD admin UI's "Build configuration file" field. - Subprojects: the new openai RTD project will be linked under the existing launchdarkly-python-sdk-ai parent, served at /projects/openai/. Follow-up RTD dashboard work is required (outside this PR): create the new openai RTD project, point the existing parent project at the new config path, add an automation rule for openai version tags, and attach the openai project as a subproject of the parent. Co-Authored-By: Claude Opus 4.7 (1M context) --- Makefile | 17 ++-- .../server-ai-openai/.readthedocs.yaml | 20 +++++ .../ai-providers/server-ai-openai/Makefile | 5 ++ .../server-ai-openai/docs}/_static/.gitkeep | 0 .../docs}/_templates/.gitkeep | 0 .../server-ai-openai/docs/api.rst | 37 ++++++++ .../server-ai-openai/docs/conf.py | 85 +++++++++++++++++++ .../server-ai-openai/docs/index.rst | 16 ++++ .../server-ai-openai/pyproject.toml | 4 + .../sdk/server-ai/.readthedocs.yaml | 2 +- packages/sdk/server-ai/Makefile | 8 +- .../sdk/server-ai/docs}/README.md | 0 packages/sdk/server-ai/docs/_static/.gitkeep | 0 .../sdk/server-ai/docs/_templates/.gitkeep | 0 .../sdk/server-ai/docs}/api-main.rst | 0 {docs => packages/sdk/server-ai/docs}/conf.py | 8 +- .../sdk/server-ai/docs}/index.rst | 0 packages/sdk/server-ai/pyproject.toml | 7 -- 18 files changed, 185 insertions(+), 24 deletions(-) create mode 100644 packages/ai-providers/server-ai-openai/.readthedocs.yaml rename {docs => packages/ai-providers/server-ai-openai/docs}/_static/.gitkeep (100%) rename {docs => packages/ai-providers/server-ai-openai/docs}/_templates/.gitkeep (100%) create mode 100644 packages/ai-providers/server-ai-openai/docs/api.rst create mode 100644 packages/ai-providers/server-ai-openai/docs/conf.py create mode 100644 packages/ai-providers/server-ai-openai/docs/index.rst rename .readthedocs.yml => packages/sdk/server-ai/.readthedocs.yaml (89%) rename {docs => packages/sdk/server-ai/docs}/README.md (100%) create mode 100644 packages/sdk/server-ai/docs/_static/.gitkeep create mode 100644 packages/sdk/server-ai/docs/_templates/.gitkeep rename {docs => packages/sdk/server-ai/docs}/api-main.rst (100%) rename {docs => packages/sdk/server-ai/docs}/conf.py (95%) rename {docs => packages/sdk/server-ai/docs}/index.rst (100%) diff --git a/Makefile b/Makefile index 0d3e79fb..9a364991 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,5 @@ PYTEST_FLAGS=-W error::SyntaxWarning -SPHINXOPTS = -W --keep-going -SPHINXBUILD = sphinx-build -SPHINXPROJ = launchdarkly-server-sdk -SOURCEDIR = docs -BUILDDIR = $(SOURCEDIR)/build - # Package paths SERVER_AI_PKG = packages/sdk/server-ai LANGCHAIN_PKG = packages/ai-providers/server-ai-langchain @@ -105,5 +99,12 @@ build-openai: #! Build openai provider package # .PHONY: docs -docs: #! Generate sphinx-based documentation - $(MAKE) -C $(SERVER_AI_PKG) docs DOCS_DIR=../../../$(SOURCEDIR) DOCS_BUILD_DIR=../../../$(BUILDDIR) +docs: docs-server-ai docs-openai #! Generate sphinx docs for all documented packages + +.PHONY: docs-server-ai +docs-server-ai: #! Generate sphinx docs for server-ai package + $(MAKE) -C $(SERVER_AI_PKG) docs + +.PHONY: docs-openai +docs-openai: #! Generate sphinx docs for openai provider package + $(MAKE) -C $(OPENAI_PKG) docs diff --git a/packages/ai-providers/server-ai-openai/.readthedocs.yaml b/packages/ai-providers/server-ai-openai/.readthedocs.yaml new file mode 100644 index 00000000..ac93ba2a --- /dev/null +++ b/packages/ai-providers/server-ai-openai/.readthedocs.yaml @@ -0,0 +1,20 @@ +version: 2 + +sphinx: + builder: html + configuration: packages/ai-providers/server-ai-openai/docs/conf.py + fail_on_warning: true + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + jobs: + pre_create_environment: + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest + create_environment: + - uv venv "${READTHEDOCS_VIRTUALENV_PATH}" + install: + - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --project packages/ai-providers/server-ai-openai --group docs diff --git a/packages/ai-providers/server-ai-openai/Makefile b/packages/ai-providers/server-ai-openai/Makefile index 8077bb0d..3ab798c1 100644 --- a/packages/ai-providers/server-ai-openai/Makefile +++ b/packages/ai-providers/server-ai-openai/Makefile @@ -27,3 +27,8 @@ lint: install build: #! Build distribution files build: install uv build --out-dir dist + +.PHONY: docs +docs: #! Generate sphinx-based documentation + uv sync --group docs + uv run sphinx-build -W --keep-going -M html docs docs/build diff --git a/docs/_static/.gitkeep b/packages/ai-providers/server-ai-openai/docs/_static/.gitkeep similarity index 100% rename from docs/_static/.gitkeep rename to packages/ai-providers/server-ai-openai/docs/_static/.gitkeep diff --git a/docs/_templates/.gitkeep b/packages/ai-providers/server-ai-openai/docs/_templates/.gitkeep similarity index 100% rename from docs/_templates/.gitkeep rename to packages/ai-providers/server-ai-openai/docs/_templates/.gitkeep diff --git a/packages/ai-providers/server-ai-openai/docs/api.rst b/packages/ai-providers/server-ai-openai/docs/api.rst new file mode 100644 index 00000000..047c6667 --- /dev/null +++ b/packages/ai-providers/server-ai-openai/docs/api.rst @@ -0,0 +1,37 @@ +OpenAI Provider API +==================== + +ldai_openai.openai_runner_factory +---------------------------------- + +.. automodule:: ldai_openai.openai_runner_factory + :members: + :special-members: __init__ + +ldai_openai.openai_model_runner +-------------------------------- + +.. automodule:: ldai_openai.openai_model_runner + :members: + :special-members: __init__ + +ldai_openai.openai_agent_runner +-------------------------------- + +.. automodule:: ldai_openai.openai_agent_runner + :members: + :special-members: __init__ + +ldai_openai.openai_agent_graph_runner +-------------------------------------- + +.. automodule:: ldai_openai.openai_agent_graph_runner + :members: + :special-members: __init__ + +ldai_openai.openai_helper +-------------------------- + +.. automodule:: ldai_openai.openai_helper + :members: + :special-members: __init__ diff --git a/packages/ai-providers/server-ai-openai/docs/conf.py b/packages/ai-providers/server-ai-openai/docs/conf.py new file mode 100644 index 00000000..df782781 --- /dev/null +++ b/packages/ai-providers/server-ai-openai/docs/conf.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- +# type: ignore +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +import os +import sys +from importlib.metadata import version as _pkg_version + +# Add the openai provider package source to the path +sys.path.insert(0, os.path.abspath('../src')) + +import ldai_openai # noqa: F401 + +# -- Project information ----------------------------------------------------- + +project = u'launchdarkly-server-sdk-ai-openai' +copyright = u'2026, LaunchDarkly' +author = u'LaunchDarkly' + +# The short X.Y version. +version = _pkg_version('launchdarkly-server-sdk-ai-openai') +# The full version, including alpha/beta/rc tags. +release = version + + +# -- General configuration --------------------------------------------------- + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['build'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# RTD sets html_theme = 'sphinx_rtd_theme' itself + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'launchdarkly-server-sdk-ai-openai-doc' + + +# -- Extension configuration ------------------------------------------------- + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'ldai': ('https://launchdarkly-python-sdk-ai.readthedocs.io/en/latest/', None), +} + +autodoc_default_options = { + 'undoc-members': False +} diff --git a/packages/ai-providers/server-ai-openai/docs/index.rst b/packages/ai-providers/server-ai-openai/docs/index.rst new file mode 100644 index 00000000..e21fd56e --- /dev/null +++ b/packages/ai-providers/server-ai-openai/docs/index.rst @@ -0,0 +1,16 @@ +LaunchDarkly Server-Side AI SDK — OpenAI Provider +================================================== + +This is the API reference for the OpenAI provider package of the `LaunchDarkly `_ Server-Side AI SDK for Python. + +The latest version of this package is on `PyPI `_, and the source code is on `GitHub `_. + +This package extends the main `launchdarkly-server-sdk-ai `_ package with OpenAI-specific runners. See that documentation for general usage of the AI SDK. + +Any types, functions, or constants that are not specifically described in this API reference should be considered implementation details that are not supported for external use; LaunchDarkly reserves the right to change them at any time and application code should not rely on them. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api diff --git a/packages/ai-providers/server-ai-openai/pyproject.toml b/packages/ai-providers/server-ai-openai/pyproject.toml index e9965bd1..47101e4a 100644 --- a/packages/ai-providers/server-ai-openai/pyproject.toml +++ b/packages/ai-providers/server-ai-openai/pyproject.toml @@ -41,6 +41,10 @@ dev = [ "isort>=5.12.0", "openai-agents>=0.0.1", ] +docs = [ + "sphinx>=6,<8", + "sphinx-rtd-theme>=1.3,<4.0", +] [build-system] requires = ["hatchling"] diff --git a/.readthedocs.yml b/packages/sdk/server-ai/.readthedocs.yaml similarity index 89% rename from .readthedocs.yml rename to packages/sdk/server-ai/.readthedocs.yaml index 038d33fc..dd46572d 100644 --- a/.readthedocs.yml +++ b/packages/sdk/server-ai/.readthedocs.yaml @@ -2,7 +2,7 @@ version: 2 sphinx: builder: html - configuration: docs/conf.py + configuration: packages/sdk/server-ai/docs/conf.py fail_on_warning: true build: diff --git a/packages/sdk/server-ai/Makefile b/packages/sdk/server-ai/Makefile index b0d21417..18746fdf 100644 --- a/packages/sdk/server-ai/Makefile +++ b/packages/sdk/server-ai/Makefile @@ -1,10 +1,4 @@ PYTEST_FLAGS=-W error::SyntaxWarning -SPHINXOPTS = -W --keep-going -SPHINXBUILD = sphinx-build - -# Configurable docs paths (can be overridden from root Makefile) -DOCS_DIR ?= docs -DOCS_BUILD_DIR ?= docs/build .PHONY: help help: #! Show this help message @@ -37,4 +31,4 @@ build: install .PHONY: docs docs: #! Generate sphinx-based documentation uv sync --group docs - uv run $(SPHINXBUILD) -M html "$(DOCS_DIR)" "$(DOCS_BUILD_DIR)" $(SPHINXOPTS) + uv run sphinx-build -W --keep-going -M html docs docs/build diff --git a/docs/README.md b/packages/sdk/server-ai/docs/README.md similarity index 100% rename from docs/README.md rename to packages/sdk/server-ai/docs/README.md diff --git a/packages/sdk/server-ai/docs/_static/.gitkeep b/packages/sdk/server-ai/docs/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/packages/sdk/server-ai/docs/_templates/.gitkeep b/packages/sdk/server-ai/docs/_templates/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/api-main.rst b/packages/sdk/server-ai/docs/api-main.rst similarity index 100% rename from docs/api-main.rst rename to packages/sdk/server-ai/docs/api-main.rst diff --git a/docs/conf.py b/packages/sdk/server-ai/docs/conf.py similarity index 95% rename from docs/conf.py rename to packages/sdk/server-ai/docs/conf.py index 47061f10..763b1cd8 100644 --- a/docs/conf.py +++ b/packages/sdk/server-ai/docs/conf.py @@ -20,7 +20,7 @@ import sys # Add the server-ai package source to the path -sys.path.insert(0, os.path.abspath('../packages/sdk/server-ai/src')) +sys.path.insert(0, os.path.abspath('../src')) import ldai @@ -49,8 +49,14 @@ 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', ] +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'ldai_openai': ('https://launchdarkly-python-sdk-ai.readthedocs.io/projects/openai/en/latest/', None), +} + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/index.rst b/packages/sdk/server-ai/docs/index.rst similarity index 100% rename from docs/index.rst rename to packages/sdk/server-ai/docs/index.rst diff --git a/packages/sdk/server-ai/pyproject.toml b/packages/sdk/server-ai/pyproject.toml index 65e79a4c..49354b6d 100644 --- a/packages/sdk/server-ai/pyproject.toml +++ b/packages/sdk/server-ai/pyproject.toml @@ -42,13 +42,6 @@ dev = [ docs = [ "sphinx>=6,<8", "sphinx-rtd-theme>=1.3,<4.0", - "certifi>=2018.4.16", - "expiringdict>=1.1.4", - "pyrfc3339>=1.0", - "jsonpickle>1.4.1", - "semver>=2.7.9", - "urllib3>=1.26.0", - "jinja2==3.1.6", ] [build-system]