Python: api doc generation setup (#342)

* api doc generation setup * remove old log file * improved check md function * update with sample code in docstring * updated script * docs update * docs update and action * removed all-extras * fixed sync command * moved install * moved action * renamed folder * fixed syntax * add python path * fix mypy and reused steps * updated merge test * undo change * slight update in poe commands * dev setup update * updated uvlock
2026-06-16 21:04:09 +08:00 · 2025-09-16 12:02:53 +02:00
parent 66fe1c957c
commit 65dd48aa1d
58 changed files with 676 additions and 2588 deletions
@@ -0,0 +1,107 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import debugpy
+import asyncio
+import json
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+from agent_framework import __version__ as agent_framework_version
+from py2docfx.__main__ import main as py2docfx_main
+
+load_dotenv()
+
+async def generate_af_docs(root_path: Path):
+    """Generate documentation for the Agent Framework using py2docfx.
+
+    This function runs the py2docfx command with the specified parameters.
+    """
+    package = {
+        "packages": [
+            {
+                "package_info": {
+                    "name": "agent-framework",
+                    "version": agent_framework_version,
+                    "install_type": "pypi",
+                    "extras": ["all"],
+                },
+                "sphinx_extensions": [
+                    "sphinxcontrib.autodoc_pydantic",
+                    "sphinx-pydantic",
+                    "sphinx.ext.autosummary"
+                ],
+                "extension_config": {
+                    "napoleon_google_docstring": True,
+                    "napoleon_preprocess_types": True,
+                    "napoleon_use_param": True,
+                    "autodoc_pydantic_field_doc_policy": "both",
+                    "autodoc_pydantic_model_show_json": False,
+                    "autodoc_pydantic_model_show_config_summary": True,
+                    "autodoc_pydantic_model_show_field_summary": True,
+                    "autodoc_pydantic_model_hide_paramlist": False,
+                    "autodoc_pydantic_model_show_json_error_strategy": "coerce",
+                    "autodoc_pydantic_settings_show_config_summary": True,
+                    "autodoc_pydantic_settings_show_field_summary": True,
+                    "python_use_unqualified_type_names": True,
+                    "autodoc_preserve_defaults": True,
+                    "autodoc_class_signature": "separated",
+                    "autodoc_typehints": "both",
+                    "autodoc_typehints_format": "fully-qualified",
+                    "autodoc_default_options": {
+                        "members": True,
+                        "member-order": "alphabetical",
+                        "undoc-members": True,
+                        "show-inheritance": True,
+                        "imported-members": True,
+                        "inherited-members": 'AFBaseModel',
+                    },
+                },
+            }
+        ],
+        "required_packages": [
+            {
+                "install_type": "pypi",
+                "name": "autodoc_pydantic",
+                "version": ">=2.0.0",
+            },
+            {
+                "install_type": "pypi",
+                "name": "sphinx-pydantic",
+            }
+        ],
+    }
+
+    args = [
+        "-o",
+        str((root_path / "docs" / "build").absolute()),
+        "-j",
+        json.dumps(package),
+    ]
+    try:
+        await py2docfx_main(args)
+    except Exception as e:
+        print(f"Error generating documentation: {e}")
+
+
+if __name__ == "__main__":
+    # Ensure the script is run from the correct directory
+    debug = False
+    if debug:
+        debugpy.listen(("localhost", 5678))
+        debugpy.wait_for_client()
+        debugpy.breakpoint()
+
+    current_path = Path(__file__).parent.parent.resolve()
+    print(f"Current path: {current_path}")
+    # ensure the dist folder exists
+    dist_path = current_path / "dist"
+    if not dist_path.exists():
+        print(" Please run `poe build` to generate the dist folder.")
+        exit(1)
+    if os.getenv("PIP_FIND_LINKS") != str(dist_path.absolute()):
+        print(f"Setting PIP_FIND_LINKS to {dist_path.absolute()}")
+        os.environ["PIP_FIND_LINKS"] = str(dist_path.absolute())
+    print(f"Generating documentation in: {current_path / 'docs' / 'build'}")
+    # Generate the documentation
+    asyncio.run(generate_af_docs(current_path))