[DOC] add API reference documentation (#7)

* add sphinx docs

* add sphinx_doc github workflow

.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 }}

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
+```

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)

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

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

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:

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:
+

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:
+

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:

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:

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:
+

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:
+