Scale api reference to multiple packages (#538)

* Scale api reference to multiple packages

* Use captioned toctrees per lib

* fix pyright

python/packages/autogen-core/docs/src/conf.py

@@ -32,24 +32,15 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.graphviz",
     "sphinx_design",
-    "sphinxcontrib.apidoc",
     "sphinx_copybutton",
     "_extension.gallery_directive",
     "myst_nb",
 ]
 suppress_warnings = ["myst.header"]
 
-apidoc_module_dir = "../../src/autogen_core"
-apidoc_output_dir = "reference/python"
-apidoc_template_dir = "_apidoc_templates"
-apidoc_separate_modules = True
-apidoc_toc_file = "index"
-apidoc_extra_args = ["--no-toc"]
 napoleon_custom_sections = [("Returns", "params_style")]
-apidoc_excluded_paths = ["./application/protos/"]
 
 templates_path = ["_templates"]
-exclude_patterns = ["reference/python/autogen_core.rst"]
 
 autoclass_content = "init"
 
@@ -112,9 +103,12 @@ html_theme_options = {
             "icon": "fa-custom fa-pydata",
         },
     ],
-
 }
 
+html_sidebars = {
+    "reference/index": [],
+    "packages/index": [],
+}
 
 html_context = {
     'display_github': True,

python/packages/autogen-core/docs/src/packages/index.md

@@ -3,7 +3,6 @@ myst:
   html_meta:
     "description lang=en": |
       AGNext packages provide a set of functionality for building multi-agent applications with AI agents.
-html_theme.nosidebar: true
 ---
 
 <style>
@@ -30,7 +29,7 @@ Implements the core functionality of the AGNext framework, providing basic build
 pip install autogen-core
 ```
 
-[{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-core/) | [{fas}`file-code;pst-color-primary` API Reference](/reference/index.md) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/agnext/tree/main/python/packages/autogen-core)
+[{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-core/) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_core/autogen_core.rst) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/agnext/tree/main/python/packages/autogen-core)
 :::
 
 :::{card} {fas}`people-group;pst-color-primary` AutoGen AgentChat
@@ -42,7 +41,7 @@ Library that is at a similar level of abstraction as AutoGen 0.2, including defa
 pip install autogen-agentchat
 ```
 
-[{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-agentchat/) | [{fas}`file-code;pst-color-primary` API Reference](/reference/index.md) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/agnext/tree/main/python/packages/autogen-agentchat)
+[{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-agentchat/) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_agentchat/autogen_agentchat.rst) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/agnext/tree/main/python/packages/autogen-agentchat)
 :::
 
 

python/packages/autogen-core/docs/src/reference/index.md

@@ -5,15 +5,51 @@ myst:
       AGNext is a community-driven project. Learn how to get involved, contribute, and connect with the community.
 ---
 
+<style>
+.api-card {
+  text-align: center;
+  font-size: 1.2rem;
+}
+
+.api-card svg {
+  font-size: 2rem;
+}
+
+
+</style>
+
 # API Reference
 
-This section contains the API reference for the AGNext core package.
+```{toctree}
+:hidden:
+:caption: AutoGen Core
+
+python/autogen_core/autogen_core
+```
 
 ```{toctree}
-:caption: Python API Reference
-:maxdepth: 1
+:hidden:
+:caption: AutoGen AgentChat
 
-python/autogen_core.components
-python/autogen_core.application
-python/autogen_core.base
+python/autogen_agentchat/autogen_agentchat
 ```
+
+::::{grid} 1 2 2 3
+:margin: 4 4 0 0
+:gutter: 1
+
+:::{grid-item-card} {fas}`cube;pst-color-primary` <br> AutoGen Core
+:link: python/autogen_core/autogen_core
+:link-type: doc
+:class-item: api-card
+:::
+
+:::{grid-item-card} {fas}`people-group;pst-color-primary` <br> AutoGen AgentChat
+:link: python/autogen_agentchat/autogen_agentchat
+:link-type: doc
+:class-item: api-card
+:::
+
+
+::::
+

python/packages/autogen-core/pyproject.toml

@@ -99,7 +99,41 @@ mypy.sequence = [
     "mypy --config-file ../../pyproject.toml --exclude src/autogen_core/application/protos src tests",
     "nbqa mypy docs/src --config-file ../../pyproject.toml",
 ]
-docs-build = "sphinx-build docs/src docs/build"
-docs-serve = "sphinx-autobuild --watch src docs/src docs/build"
-docs-check = "sphinx-build --fail-on-warning docs/src docs/build"
+
+# Docs
 docs-clean = "rm -rf docs/build && rm -rf docs/src/reference/python/"
+
+docs-apidoc-core = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_core src/autogen_core src/autogen_core/application/protos/"
+docs-apidoc-agentchat = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_agentchat ../autogen-agentchat/src/autogen_agentchat"
+docs-apidoc-all = [
+    "docs-apidoc-core",
+    "docs-apidoc-agentchat"
+]
+
+# Inline tables are WAY easier to read but for some reason they break pyright. So we have to write it out this way.
+# Example of inline table:
+# docs-build = [
+#     "docs-apidoc-all",
+#     { cmd = "sphinx-build docs/src docs/build" }
+# ]
+
+[[tool.poe.tasks.docs-build.sequence]]
+ref = "docs-apidoc-all"
+
+[[tool.poe.tasks.docs-build.sequence]]
+cmd = "sphinx-build docs/src docs/build"
+
+[[tool.poe.tasks.docs-serve.sequence]]
+ref = "docs-apidoc-all"
+
+[[tool.poe.tasks.docs-serve.sequence]]
+cmd = "sphinx-autobuild --watch src docs/src docs/build"
+
+[[tool.poe.tasks.docs-check.sequence]]
+ref = "docs-apidoc-all"
+
+[[tool.poe.tasks.docs-check.sequence]]
+ref = "docs-apidoc-all"
+
+[[tool.poe.tasks.docs-check.sequence]]
+cmd = "sphinx-build --fail-on-warning docs/src docs/build"