From b15ef783d7ec8035a8eecd408b89fdf96c12d7c4 Mon Sep 17 00:00:00 2001 From: kylerohn-msft Date: Thu, 30 Jul 2026 11:49:09 -0700 Subject: [PATCH 1/3] initial sphinx docs configuration --- docs/Makefile | 20 +++++++++++ docs/make.bat | 35 +++++++++++++++++++ ...ents.authentication.entra_auth_sidecar.rst | 14 ++++++++ .../microsoft_agents.authentication.msal.rst | 14 ++++++++ .../microsoft_agents.authentication.rst | 9 +++++ docs/source/conf.py | 27 ++++++++++++++ .../microsoft_agents.hosting.aiohttp.rst | 14 ++++++++ .../hosting/microsoft_agents.hosting.core.rst | 14 ++++++++ .../microsoft_agents.hosting.dialogs.rst | 14 ++++++++ .../microsoft_agents.hosting.fastapi.rst | 14 ++++++++ .../microsoft_agents.hosting.msteams.rst | 14 ++++++++ .../hosting/microsoft_agents.hosting.rst | 14 ++++++++ .../microsoft_agents.hosting.slack.rst | 14 ++++++++ .../microsoft_agents.hosting.teams.rst | 14 ++++++++ docs/source/index.rst | 25 +++++++++++++ docs/source/microsoft_agents.activity.rst | 14 ++++++++ .../microsoft_agents.copilotstudio.client.rst | 14 ++++++++ .../storage/microsoft_agents.storage.blob.rst | 14 ++++++++ .../microsoft_agents.storage.cosmos.rst | 14 ++++++++ .../storage/microsoft_agents.storage.rst | 9 +++++ 20 files changed, 321 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/authentication/microsoft_agents.authentication.entra_auth_sidecar.rst create mode 100644 docs/source/authentication/microsoft_agents.authentication.msal.rst create mode 100644 docs/source/authentication/microsoft_agents.authentication.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/hosting/microsoft_agents.hosting.aiohttp.rst create mode 100644 docs/source/hosting/microsoft_agents.hosting.core.rst create mode 100644 docs/source/hosting/microsoft_agents.hosting.dialogs.rst create mode 100644 docs/source/hosting/microsoft_agents.hosting.fastapi.rst create mode 100644 docs/source/hosting/microsoft_agents.hosting.msteams.rst create mode 100644 docs/source/hosting/microsoft_agents.hosting.rst create mode 100644 docs/source/hosting/microsoft_agents.hosting.slack.rst create mode 100644 docs/source/hosting/microsoft_agents.hosting.teams.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/microsoft_agents.activity.rst create mode 100644 docs/source/microsoft_agents.copilotstudio.client.rst create mode 100644 docs/source/storage/microsoft_agents.storage.blob.rst create mode 100644 docs/source/storage/microsoft_agents.storage.cosmos.rst create mode 100644 docs/source/storage/microsoft_agents.storage.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal 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 = source +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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/authentication/microsoft_agents.authentication.entra_auth_sidecar.rst b/docs/source/authentication/microsoft_agents.authentication.entra_auth_sidecar.rst new file mode 100644 index 00000000..d5249c31 --- /dev/null +++ b/docs/source/authentication/microsoft_agents.authentication.entra_auth_sidecar.rst @@ -0,0 +1,14 @@ +microsoft\_agents.authentication.entra_auth_sidecar +========================================================== + +.. include:: ../../../libraries/microsoft-agents-authentication-entra-auth-sidecar/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.authentication.entra_auth_sidecar + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/authentication/microsoft_agents.authentication.msal.rst b/docs/source/authentication/microsoft_agents.authentication.msal.rst new file mode 100644 index 00000000..2e1a5f32 --- /dev/null +++ b/docs/source/authentication/microsoft_agents.authentication.msal.rst @@ -0,0 +1,14 @@ +microsoft_agents.authentication.msal +============================================ + +.. include:: ../../../libraries/microsoft-agents-authentication-msal/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.authentication.msal + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/authentication/microsoft_agents.authentication.rst b/docs/source/authentication/microsoft_agents.authentication.rst new file mode 100644 index 00000000..4a68eabb --- /dev/null +++ b/docs/source/authentication/microsoft_agents.authentication.rst @@ -0,0 +1,9 @@ +microsoft\_agents.authentication +======================================== + +.. toctree:: + :maxdepth: 1 + :caption: Packages: + + microsoft_agents.authentication.msal + microsoft_agents.authentication.entra_auth_sidecar \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..8f4f9fcc --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,27 @@ +# 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 = "Python Agents SDK" +copyright = "2026, Microsoft" +author = "Microsoft" +release = "v1.2.0" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.autodoc", "myst_parser"] + +templates_path = ["_templates"] +exclude_patterns = [] + +# -- 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"] diff --git a/docs/source/hosting/microsoft_agents.hosting.aiohttp.rst b/docs/source/hosting/microsoft_agents.hosting.aiohttp.rst new file mode 100644 index 00000000..8708a78a --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.aiohttp.rst @@ -0,0 +1,14 @@ +microsoft_agents.hosting.aiohttp +======================================== + +.. include:: ../../../libraries/microsoft-agents-hosting-aiohttp/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.hosting.aiohttp + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/hosting/microsoft_agents.hosting.core.rst b/docs/source/hosting/microsoft_agents.hosting.core.rst new file mode 100644 index 00000000..dc87505e --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.core.rst @@ -0,0 +1,14 @@ +microsoft_agents.hosting.core +===================================== + +.. include:: ../../../libraries/microsoft-agents-hosting-core/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.hosting.core + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/hosting/microsoft_agents.hosting.dialogs.rst b/docs/source/hosting/microsoft_agents.hosting.dialogs.rst new file mode 100644 index 00000000..7f92ce10 --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.dialogs.rst @@ -0,0 +1,14 @@ +microsoft_agents.hosting.dialogs +======================================== + +.. include:: ../../../libraries/microsoft-agents-hosting-dialogs/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.hosting.dialogs + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/hosting/microsoft_agents.hosting.fastapi.rst b/docs/source/hosting/microsoft_agents.hosting.fastapi.rst new file mode 100644 index 00000000..c26c3b5d --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.fastapi.rst @@ -0,0 +1,14 @@ +microsoft_agents.hosting.fastapi +======================================== + +.. include:: ../../../libraries/microsoft-agents-hosting-fastapi/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.hosting.fastapi + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/hosting/microsoft_agents.hosting.msteams.rst b/docs/source/hosting/microsoft_agents.hosting.msteams.rst new file mode 100644 index 00000000..2bda4d03 --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.msteams.rst @@ -0,0 +1,14 @@ +microsoft_agents.hosting.msteams +======================================== + +.. include:: ../../../libraries/microsoft-agents-hosting-msteams/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.hosting.msteams + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/hosting/microsoft_agents.hosting.rst b/docs/source/hosting/microsoft_agents.hosting.rst new file mode 100644 index 00000000..56551d40 --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.rst @@ -0,0 +1,14 @@ +microsoft\_agents.hosting +================================ + +.. toctree:: + :maxdepth: 1 + :caption: Packages: + + microsoft_agents.hosting.core + microsoft_agents.hosting.aiohttp + microsoft_agents.hosting.dialogs + microsoft_agents.hosting.fastapi + microsoft_agents.hosting.msteams + microsoft_agents.hosting.teams + microsoft_agents.hosting.slack \ No newline at end of file diff --git a/docs/source/hosting/microsoft_agents.hosting.slack.rst b/docs/source/hosting/microsoft_agents.hosting.slack.rst new file mode 100644 index 00000000..d2809cdc --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.slack.rst @@ -0,0 +1,14 @@ +microsoft_agents.hosting.slack +====================================== + +.. include:: ../../../libraries/microsoft-agents-hosting-slack/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.hosting.slack + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/hosting/microsoft_agents.hosting.teams.rst b/docs/source/hosting/microsoft_agents.hosting.teams.rst new file mode 100644 index 00000000..180a4e11 --- /dev/null +++ b/docs/source/hosting/microsoft_agents.hosting.teams.rst @@ -0,0 +1,14 @@ +microsoft_agents.hosting.teams +====================================== + +.. include:: ../../../libraries/microsoft-agents-hosting-teams/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.hosting.teams + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..30cc4c47 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,25 @@ +.. agents-for-js documentation master file, created by + sphinx-quickstart on Wed Jul 29 12:21:35 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Python Agents SDK API Reference +=========================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + microsoft_agents.activity + +.. toctree:: + :maxdepth: 2 + + hosting/microsoft_agents.hosting + authentication/microsoft_agents.authentication + storage/microsoft_agents.storage + +.. toctree:: + :maxdepth: 1 + + microsoft_agents.copilotstudio.client \ No newline at end of file diff --git a/docs/source/microsoft_agents.activity.rst b/docs/source/microsoft_agents.activity.rst new file mode 100644 index 00000000..b2857577 --- /dev/null +++ b/docs/source/microsoft_agents.activity.rst @@ -0,0 +1,14 @@ +microsoft_agents.activity +================================== + +.. include:: ../../libraries/microsoft-agents-activity/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.activity + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/microsoft_agents.copilotstudio.client.rst b/docs/source/microsoft_agents.copilotstudio.client.rst new file mode 100644 index 00000000..cb792f52 --- /dev/null +++ b/docs/source/microsoft_agents.copilotstudio.client.rst @@ -0,0 +1,14 @@ +microsoft_agents.copilotstudio.client +============================================= + +.. include:: ../../libraries/microsoft-agents-copilotstudio-client/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.copilotstudio.client + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/storage/microsoft_agents.storage.blob.rst b/docs/source/storage/microsoft_agents.storage.blob.rst new file mode 100644 index 00000000..dc892595 --- /dev/null +++ b/docs/source/storage/microsoft_agents.storage.blob.rst @@ -0,0 +1,14 @@ +microsoft_agents.storage.blob +===================================== + +.. include:: ../../../libraries/microsoft-agents-storage-blob/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.storage.blob + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/storage/microsoft_agents.storage.cosmos.rst b/docs/source/storage/microsoft_agents.storage.cosmos.rst new file mode 100644 index 00000000..3810df65 --- /dev/null +++ b/docs/source/storage/microsoft_agents.storage.cosmos.rst @@ -0,0 +1,14 @@ +microsoft\_agents.storage.cosmos +======================================= + +.. include:: ../../../libraries/microsoft-agents-storage-cosmos/readme.md + :parser: myst_parser.sphinx_ + +API reference +------------- + +.. automodule:: microsoft_agents.storage.cosmos + :members: + :imported-members: + :show-inheritance: + :undoc-members: diff --git a/docs/source/storage/microsoft_agents.storage.rst b/docs/source/storage/microsoft_agents.storage.rst new file mode 100644 index 00000000..292c09d8 --- /dev/null +++ b/docs/source/storage/microsoft_agents.storage.rst @@ -0,0 +1,9 @@ +microsoft_agents.activity +================================== + +.. toctree:: + :maxdepth: 1 + :caption: Packages: + + microsoft_agents.storage.blob + microsoft_agents.storage.cosmos \ No newline at end of file From 300590ac294e94e9ccb98a31c4ecacfa44ab2bd1 Mon Sep 17 00:00:00 2001 From: kylerohn-msft Date: Fri, 7 Aug 2026 13:26:59 -0700 Subject: [PATCH 2/3] update deps --- dev_dependencies.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/dev_dependencies.txt b/dev_dependencies.txt index abd81559..0f3a921b 100644 --- a/dev_dependencies.txt +++ b/dev_dependencies.txt @@ -3,4 +3,7 @@ pytest-asyncio pytest-aiohttp pytest-mock pre-commit -click \ No newline at end of file +click +sphinx +myst-parser +sphinx-rtd-theme \ No newline at end of file From efb8bfb7eb0039b2bb16519dfc3f14f62185e37f Mon Sep 17 00:00:00 2001 From: kylerohn-msft Date: Fri, 7 Aug 2026 14:00:06 -0700 Subject: [PATCH 3/3] add README to docs front page and create actions script --- .github/workflows/gh-pages.yml | 67 ++++++++++++++++++++++++++++++++++ docs/source/index.rst | 7 +++- 2 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/gh-pages.yml diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 00000000..db27fbea --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,67 @@ +# Simple workflow for deploying static content to GitHub Pages +name: Build and Deploy Docs + +on: + # Runs on pushes targeting the default branch + push: + branches: + - 'release/*' + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: "3.12" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r dev_dependencies.txt + pip install ./libraries/microsoft-agents-activity/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-authentication-msal/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-authentication-entra-auth-sidecar/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-copilotstudio-client/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-hosting-aiohttp/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-hosting-core/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-hosting-teams/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-hosting-msteams/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-hosting-dialogs/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-hosting-fastapi/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-hosting-slack/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-storage-blob/ --config-settings editable_mode=compat + pip install ./libraries/microsoft-agents-storage-cosmos/ --config-settings editable_mode=compat + - name: Build Docs + run: | + cd docs + make html + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + # Upload entire repository + path: './docs/build/html' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/docs/source/index.rst b/docs/source/index.rst index 30cc4c47..c10b5248 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,11 +4,14 @@ contain the root `toctree` directive. Python Agents SDK API Reference -=========================== +============================================ + +.. include:: ../../README.md + :parser: myst_parser.sphinx_ .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: Packages: microsoft_agents.activity