From 06929d7fbc2dabe88bc308450c65d16f8ce38bcb Mon Sep 17 00:00:00 2001 From: Xuchen Pan <32844285+pan-x-c@users.noreply.github.com> Date: Mon, 15 Jan 2024 19:03:39 +0800 Subject: [PATCH] [DOC] add API reference documentation (#7) * add sphinx docs * add sphinx_doc github workflow --- .github/workflows/sphinx_docs.yml | 30 +++++ docs/README.md | 125 ++++++++++++++++++ docs/sphinx_doc/Makefile | 20 +++ docs/sphinx_doc/make.bat | 35 +++++ docs/sphinx_doc/requirements.txt | 11 ++ docs/sphinx_doc/source/agentscope.agents.rst | 18 +++ docs/sphinx_doc/source/agentscope.configs.rst | 11 ++ docs/sphinx_doc/source/agentscope.memory.rst | 20 +++ docs/sphinx_doc/source/agentscope.models.rst | 34 +++++ .../source/agentscope.pipelines.rst | 18 +++ docs/sphinx_doc/source/agentscope.rpc.rst | 20 +++ docs/sphinx_doc/source/agentscope.rst | 40 ++++++ .../source/agentscope.service.code.rst | 11 ++ .../source/agentscope.service.file.rst | 28 ++++ .../source/agentscope.service.retrieval.rst | 20 +++ docs/sphinx_doc/source/agentscope.service.rst | 14 ++ .../source/agentscope.service.sql_query.rst | 27 ++++ .../agentscope.service.text_processing.rst | 12 ++ .../source/agentscope.service.web_search.rst | 11 ++ docs/sphinx_doc/source/agentscope.utils.rst | 51 +++++++ docs/sphinx_doc/source/agentscope.web_ui.rst | 11 ++ docs/sphinx_doc/source/conf.py | 68 ++++++++++ docs/sphinx_doc/source/index.rst | 41 ++++++ docs/sphinx_doc/source/tutorial/main.md | 3 + setup.py | 8 +- 25 files changed, 686 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/sphinx_docs.yml create mode 100644 docs/README.md create mode 100644 docs/sphinx_doc/Makefile create mode 100644 docs/sphinx_doc/make.bat create mode 100644 docs/sphinx_doc/requirements.txt create mode 100644 docs/sphinx_doc/source/agentscope.agents.rst create mode 100644 docs/sphinx_doc/source/agentscope.configs.rst create mode 100644 docs/sphinx_doc/source/agentscope.memory.rst create mode 100644 docs/sphinx_doc/source/agentscope.models.rst create mode 100644 docs/sphinx_doc/source/agentscope.pipelines.rst create mode 100644 docs/sphinx_doc/source/agentscope.rpc.rst create mode 100644 docs/sphinx_doc/source/agentscope.rst create mode 100644 docs/sphinx_doc/source/agentscope.service.code.rst create mode 100644 docs/sphinx_doc/source/agentscope.service.file.rst create mode 100644 docs/sphinx_doc/source/agentscope.service.retrieval.rst create mode 100644 docs/sphinx_doc/source/agentscope.service.rst create mode 100644 docs/sphinx_doc/source/agentscope.service.sql_query.rst create mode 100644 docs/sphinx_doc/source/agentscope.service.text_processing.rst create mode 100644 docs/sphinx_doc/source/agentscope.service.web_search.rst create mode 100644 docs/sphinx_doc/source/agentscope.utils.rst create mode 100644 docs/sphinx_doc/source/agentscope.web_ui.rst create mode 100644 docs/sphinx_doc/source/conf.py create mode 100644 docs/sphinx_doc/source/index.rst create mode 100644 docs/sphinx_doc/source/tutorial/main.md diff --git a/.github/workflows/sphinx_docs.yml b/.github/workflows/sphinx_docs.yml new file mode 100644 index 000000000..117c22efd --- /dev/null +++ b/.github/workflows/sphinx_docs.yml @@ -0,0 +1,30 @@ +name: Deploy Sphinx documentation to Pages + +on: + release: + types: [published] + +jobs: + pages: + runs-on: ubuntu-latest + timeout-minutes: 20 + env: + OS: ${{ matrix.os }} + PYTHON: '3.9' + steps: + - uses: actions/checkout@master + - name: Setup Python ${{ matrix.python-version }} + uses: actions/setup-python@master + with: + python_version: ${{ matrix.python-version }} + - id: deployment + uses: sphinx-notes/pages@v3 + with: + documentation_path: ./docs/sphinx_doc/source + python_version: ${{ matrix.python-version }} + publish: false + requirements_path: ./docs/sphinx_doc/requirements.txt + - uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ${{ steps.deployment.outputs.artifact }} \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..5aab32072 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,125 @@ +# AgentScope Documentation + +## Build Documentation + +Please use the following commands to build sphinx doc of AgentScope. + +```shell +# step 1: Install dependencies +pip install sphinx sphinx-autobuild sphinx_rtd_theme myst-parser sphinxcontrib-mermaid + +# step 2: go into the sphinx_doc dir +cd sphinx_doc + +# step 3: build the sphinx doc +make clean html + +# step 4: view sphinx_doc/build/html/index.html using your browser +``` + +## Update Documentation (for developer) + +### Add doc for new packages + +``` +src +└── agentscope + ├── ... + └── new_package + ├── __init__.py + └── new_module.py +``` + +If a new package (`agentscope/new_package`) is added , please add the corresponding documents as follows: + +1. use the following script to generate template script (`sphinx_doc/source/agentscope.new_package.rst`) of new packages. + +```shell +cd sphinx_doc +sphinx-apidoc -o source ../../src/agentscope +``` + +2. edit `sphinx_doc/source/agentscope.new_package.rst`, modify the content of the generated template script. For example, modify + +``` +agentscope.new\_package package +=============================== + +Submodules +---------- + +agentscope.new\_package.new\_module module +------------------------------------------- +... + +Module contents +--------------- +... +``` + +to + +``` +NewPackage package +================== + +new\_module module +------------------ +... +``` + +1. modify the `sphinx_doc/source/index.rst`, add the new package into the table of contents. + +``` +.. toctree:: + :maxdepth: 2 + :hidden: + :glob: + :caption: AgentScope API Reference + + agentscope.agents + ... + agentscope.new_package + agentscope +``` + +4. rebuild the sphinx doc of AgentScope + +``` +make clean +make html +``` + +### Add doc for new modules + +``` +src +└── agentscope + ├── ... + └── existing_package + ├── __init__.py + ├── existing_module.py + ├── ... + └── new_module.py +``` + +If a new module (agentscope/existing_package/new_module.py) is added , please add the corresponding documents as follows: + +1. edit `sphinx_doc/source/agentscope.existing_package.rst` and add the following content. + +``` +new\_module module +------------------ + +.. automodule:: agentscope.existing_package.new_module + :members: + :undoc-members: + :show-inheritance: +``` + +2. rebuild the sphinx doc of AgentScope + +``` +make clean +make html +``` diff --git a/docs/sphinx_doc/Makefile b/docs/sphinx_doc/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/docs/sphinx_doc/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/sphinx_doc/make.bat b/docs/sphinx_doc/make.bat new file mode 100644 index 000000000..747ffb7b3 --- /dev/null +++ b/docs/sphinx_doc/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/sphinx_doc/requirements.txt b/docs/sphinx_doc/requirements.txt new file mode 100644 index 000000000..6992bd9b3 --- /dev/null +++ b/docs/sphinx_doc/requirements.txt @@ -0,0 +1,11 @@ +loguru +tiktoken +pillow +requests +openai +numpy +sphinx +sphinx-autobuild +sphinx_rtd_theme +sphinxcontrib-mermaid +myst-parser \ No newline at end of file diff --git a/docs/sphinx_doc/source/agentscope.agents.rst b/docs/sphinx_doc/source/agentscope.agents.rst new file mode 100644 index 000000000..d8c576d1a --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.agents.rst @@ -0,0 +1,18 @@ +Agents package +========================== + +agent module +------------------------------- + +.. automodule:: agentscope.agents.agent + :members: + :undoc-members: + :show-inheritance: + +rpc_agent module +------------------------------- + +.. automodule:: agentscope.agents.rpc_agent + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/sphinx_doc/source/agentscope.configs.rst b/docs/sphinx_doc/source/agentscope.configs.rst new file mode 100644 index 000000000..8e5d96d96 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.configs.rst @@ -0,0 +1,11 @@ +Configs package +========================== + +model\_config module +--------------------------------------- + +.. automodule:: agentscope.configs.model_config + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.memory.rst b/docs/sphinx_doc/source/agentscope.memory.rst new file mode 100644 index 000000000..b8f3bee32 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.memory.rst @@ -0,0 +1,20 @@ +Memory package +========================== + + +memory module +-------------------------------- + +.. automodule:: agentscope.memory.memory + :members: + :undoc-members: + :show-inheritance: + +temporary\_memory module +------------------------------------------- + +.. automodule:: agentscope.memory.temporary_memory + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.models.rst b/docs/sphinx_doc/source/agentscope.models.rst new file mode 100644 index 000000000..e2f52c50f --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.models.rst @@ -0,0 +1,34 @@ +Models package +========================== + +model module +------------------------------- + +.. automodule:: agentscope.models.model + :members: + :undoc-members: + :show-inheritance: + +openai\_model module +--------------------------------------- + +.. automodule:: agentscope.models.openai_model + :members: + :undoc-members: + :show-inheritance: + +post\_model module +------------------------------------- + +.. automodule:: agentscope.models.post_model + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: agentscope.models + :members: load_model_by_name, clear_model_configs, read_model_configs + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx_doc/source/agentscope.pipelines.rst b/docs/sphinx_doc/source/agentscope.pipelines.rst new file mode 100644 index 000000000..6a387f3eb --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.pipelines.rst @@ -0,0 +1,18 @@ +Pipelines package +============================= + +pipeline module +------------------------------------- + +.. automodule:: agentscope.pipelines.pipeline + :members: + :undoc-members: + :show-inheritance: + +functional module +--------------------------------------- + +.. automodule:: agentscope.pipelines.functional + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx_doc/source/agentscope.rpc.rst b/docs/sphinx_doc/source/agentscope.rpc.rst new file mode 100644 index 000000000..42a61abe9 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.rpc.rst @@ -0,0 +1,20 @@ +RPC package +======================= + +rpc\_agent\_client module +----------------------------------------- + +.. automodule:: agentscope.rpc.rpc_agent_client + :members: + :undoc-members: + :show-inheritance: + + +rpc\_agent\_pb2\_grpc module +-------------------------------------------- + +.. automodule:: agentscope.rpc.rpc_agent_pb2_grpc + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.rst b/docs/sphinx_doc/source/agentscope.rst new file mode 100644 index 000000000..42018ef12 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.rst @@ -0,0 +1,40 @@ +Module contents +=============== + + +file\_manager module +-------------------------------- + +.. automodule:: agentscope.file_manager + :noindex: + :members: + :undoc-members: + :show-inheritance: + +message module +-------------------------- + +.. automodule:: agentscope.message + :noindex: + :members: + :undoc-members: + :show-inheritance: + +msghub module +------------------------- + +.. automodule:: agentscope.msghub + :noindex: + :members: + :undoc-members: + :show-inheritance: + +prompt module +------------------------- + +.. automodule:: agentscope.prompt + :noindex: + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.service.code.rst b/docs/sphinx_doc/source/agentscope.service.code.rst new file mode 100644 index 000000000..280ff48a5 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.service.code.rst @@ -0,0 +1,11 @@ +Code package +================================ + +exec\_python module +-------------------------------------------- + +.. automodule:: agentscope.service.code.exec_python + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.service.file.rst b/docs/sphinx_doc/source/agentscope.service.file.rst new file mode 100644 index 000000000..ede1c10a2 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.service.file.rst @@ -0,0 +1,28 @@ +File package +================================ + + +common module +-------------------------------------- + +.. automodule:: agentscope.service.file.common + :members: + :undoc-members: + :show-inheritance: + +json module +------------------------------------ + +.. automodule:: agentscope.service.file.json + :members: + :undoc-members: + :show-inheritance: + +text module +------------------------------------ + +.. automodule:: agentscope.service.file.text + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.service.retrieval.rst b/docs/sphinx_doc/source/agentscope.service.retrieval.rst new file mode 100644 index 000000000..8b3686a43 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.service.retrieval.rst @@ -0,0 +1,20 @@ +Retrieval package +===================================== + + +retrieval\_from\_list module +---------------------------------------------------------- + +.. automodule:: agentscope.service.retrieval.retrieval_from_list + :members: + :undoc-members: + :show-inheritance: + +similarity module +----------------------------------------------- + +.. automodule:: agentscope.service.retrieval.similarity + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.service.rst b/docs/sphinx_doc/source/agentscope.service.rst new file mode 100644 index 000000000..6c7666345 --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.service.rst @@ -0,0 +1,14 @@ +Service package +=========================== + + +.. toctree:: + :maxdepth: 4 + + agentscope.service.code + agentscope.service.file + agentscope.service.retrieval + agentscope.service.sql_query + agentscope.service.text_processing + agentscope.service.web_search + diff --git a/docs/sphinx_doc/source/agentscope.service.sql_query.rst b/docs/sphinx_doc/source/agentscope.service.sql_query.rst new file mode 100644 index 000000000..6e748635b --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.service.sql_query.rst @@ -0,0 +1,27 @@ +SQL query package +====================================== + +mongodb module +--------------------------------------------- + +.. automodule:: agentscope.service.sql_query.mongodb + :members: + :undoc-members: + :show-inheritance: + +mysql module +------------------------------------------- + +.. automodule:: agentscope.service.sql_query.mysql + :members: + :undoc-members: + :show-inheritance: + +sqlite module +-------------------------------------------- + +.. automodule:: agentscope.service.sql_query.sqlite + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.service.text_processing.rst b/docs/sphinx_doc/source/agentscope.service.text_processing.rst new file mode 100644 index 000000000..a7558d16f --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.service.text_processing.rst @@ -0,0 +1,12 @@ +Text processing package +============================================ + + +summarization module +--------------------------------------------------------- + +.. automodule:: agentscope.service.text_processing.summarization + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.service.web_search.rst b/docs/sphinx_doc/source/agentscope.service.web_search.rst new file mode 100644 index 000000000..895ab915c --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.service.web_search.rst @@ -0,0 +1,11 @@ +Web search package +======================================= + +search module +--------------------------------------------- + +.. automodule:: agentscope.service.web_search.search + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx_doc/source/agentscope.utils.rst b/docs/sphinx_doc/source/agentscope.utils.rst new file mode 100644 index 000000000..22f08054b --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.utils.rst @@ -0,0 +1,51 @@ +Utils package +========================= + + +common module +------------------------------- + +.. automodule:: agentscope.utils.common + :members: + :undoc-members: + :show-inheritance: + +enums module +------------------------------ + +.. automodule:: agentscope.utils.enums + :members: + :undoc-members: + :show-inheritance: + +logging\_utils module +--------------------------------------- + +.. automodule:: agentscope.utils.logging_utils + :members: + :undoc-members: + :show-inheritance: + +monitor module +-------------------------------- + +.. automodule:: agentscope.utils.monitor + :members: + :undoc-members: + :show-inheritance: + +token\_utils module +------------------------------------- + +.. automodule:: agentscope.utils.token_utils + :members: + :undoc-members: + :show-inheritance: + +tools module +------------------------------ + +.. automodule:: agentscope.utils.tools + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx_doc/source/agentscope.web_ui.rst b/docs/sphinx_doc/source/agentscope.web_ui.rst new file mode 100644 index 000000000..edc09867a --- /dev/null +++ b/docs/sphinx_doc/source/agentscope.web_ui.rst @@ -0,0 +1,11 @@ +Web UI package +========================== + +app module +----------------------------- + +.. automodule:: agentscope.web_ui.app + :members: + :undoc-members: gradio_groupchat + :show-inheritance: + diff --git a/docs/sphinx_doc/source/conf.py b/docs/sphinx_doc/source/conf.py new file mode 100644 index 000000000..221d8ff67 --- /dev/null +++ b/docs/sphinx_doc/source/conf.py @@ -0,0 +1,68 @@ +# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys + +# sys.path.insert(0, os.path.abspath("../../../src/agentscope")) + + +# -- Project information ----------------------------------------------------- + +project = "AgentScope" +copyright = "2024, Alibaba Tongyi Lab" +author = "SysML team of Alibaba Tongyi Lab" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinxcontrib.mermaid", + "myst_parser", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +html_theme_options = { + "navigation_depth": 4, +} + +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} diff --git a/docs/sphinx_doc/source/index.rst b/docs/sphinx_doc/source/index.rst new file mode 100644 index 000000000..1b404003c --- /dev/null +++ b/docs/sphinx_doc/source/index.rst @@ -0,0 +1,41 @@ +.. AgentScope documentation master file, created by + sphinx-quickstart on Fri Jan 5 17:53:54 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +:github_url: https://github.com/alibaba/agentscope + +AgentScope Documentation +====================================== + +.. toctree:: + :maxdepth: 2 + :glob: + :caption: AgentScope API Reference + + agentscope.agents + agentscope.configs + agentscope.memory + agentscope.models + agentscope.pipelines + agentscope.service + agentscope.rpc + agentscope.utils + agentscope.web_ui + agentscope + +.. include:: tutorial/main.md + :parser: myst_parser.sphinx_ + +.. toctree:: + :maxdepth: 1 + :glob: + :hidden: + :caption: AgentScope Tutorial + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/sphinx_doc/source/tutorial/main.md b/docs/sphinx_doc/source/tutorial/main.md new file mode 100644 index 000000000..f0338300d --- /dev/null +++ b/docs/sphinx_doc/source/tutorial/main.md @@ -0,0 +1,3 @@ +# AgentScope Tutorial + +Comming Soon diff --git a/setup.py b/setup.py index efb9c9d50..a1b79c76c 100644 --- a/setup.py +++ b/setup.py @@ -21,7 +21,13 @@ service_requires = ["docker", "pymongo", "pymysql"] -doc_requires = ["sphinx", "sphinx-autobuild", "sphinx_rtd_theme"] +doc_requires = [ + "sphinx", + "sphinx-autobuild", + "sphinx_rtd_theme", + "myst-parser", + "sphinxcontrib-mermaid", +] test_requires = ["pytest", "pytest-cov", "pre-commit"]