opendilab · ruiheng123 · Jul 12, 2024 · Jul 12, 2024 · Jul 14, 2024 · Jul 15, 2024
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,38 @@
+name: Deploy Sphinx Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout the repository
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade -r requirements-doc.txt
+        pip install -e .
+        pip install sphinx sphinx-rtd-theme recommonmark
+
+    - name: Build the Sphinx documentation
+      run: |
+        cd docs
+        make html
+        cp ../.nojekyll ./build/html/.nojekyll
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/build/html
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -19,7 +19,7 @@ jobs:
       fail-fast: false
       matrix:
         os:
-          - 'self-hosted-ubuntu'
+          - 'self-hosted'
           - 'macos-12'
         python-version:
           - '3.8'
@@ -30,6 +30,8 @@ jobs:
         if: ${{ runner.os == 'Linux' }}
         shell: bash
         run: |
+          sudo apt-get update -y
+          sudo apt-get install swig -y
           echo "OS_NAME=Linux" >> $GITHUB_ENV
           echo "IS_WIN=" >> $GITHUB_ENV
           echo "IS_MAC=" >> $GITHUB_ENV
@@ -64,13 +66,13 @@ jobs:
         shell: bash
         run: |
           python -m pip install --upgrade pip
-          pip install --upgrade flake8 setuptools wheel twine
-          pip install -r requirements.txt
-          pip install -r requirements-build.txt
-          pip install -r requirements-test.txt
+          pip install --no-cache-dir --upgrade flake8 setuptools wheel twine -i https://pypi.tuna.tsinghua.edu.cn/simple
+          pip install -r requirements.txt --upgrade --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple
+          pip install -r requirements-build.txt --upgrade --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple
+          pip install -r requirements-test.txt --upgrade --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple
           pip uninstall DI-engine -y
-          pip install git+http://github.com/opendilab/DI-engine.git@main#egg=DI-engine[common_env]
-          pip install transformers
+          pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple git+http://github.com/opendilab/DI-engine.git@main#egg=DI-engine[common_env] --upgrade
+          pip install --no-cache-dir transformers --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple
       - name: Run unittest on MacOS or Linux
         if: ${{ env.OS_NAME == 'MacOS' || env.OS_NAME == 'Linux'}}
         env:

diff --git a/.nojekyll b/.nojekyll
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,36 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/en/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+  - htmlzip
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: requirements-doc.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,12 @@
+2024.07.12 (v0.1.0)
+- env: SumToThree env from pooltool(#227)
+- algo: UniZero (#232)
+- algo: ReZero (#238)
+- feature: add logs and config documentations (#220)
+- polish: polish atari_env_action_space_map, fix test_muzero_game_buffer
+- polish: polish release.yml
+- style: update discord link and add a new badge in readme (#221)
+
 2024.04.12 (v0.0.5)
 - env: MemoryEnv (#197)
 - env: mountain_car (#181)

diff --git a/README.md b/README.md
diff --git a/README.zh.md b/README.zh.md
diff --git a/assets/algo_overview/efficientzero_overview.pdf b/assets/algo_overview/efficientzero_overview.pdf
diff --git a/assets/algo_overview/gumbel_muzero_overview.pdf b/assets/algo_overview/gumbel_muzero_overview.pdf
diff --git a/assets/algo_overview/muzero_overview.pdf b/assets/algo_overview/muzero_overview.pdf
diff --git a/assets/algo_overview/sampled_muzero_overview.pdf b/assets/algo_overview/sampled_muzero_overview.pdf
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,11 @@
+*.puml.eps
+*.puml.jpg
+*.puml.svg
+.DS_Store
+../build/
+source/_build
+_build/
+.vscode/
+venv/
+.idea/
+src/pytorch-sphinx-theme/
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,62 +1,35 @@
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS         ?=
-SPHINXBUILD        ?= $(shell which sphinx-build)
-SPHINXMULTIVERSION ?= $(shell which sphinx-multiversion)
-SOURCEDIR          ?= source
-BUILDDIR           ?= build
-
 # Minimal makefile for Sphinx documentation
-DIAGRAMS_MK := ${SOURCEDIR}/diagrams.mk
-DIAGRAMS    := $(MAKE) -f "${DIAGRAMS_MK}" SOURCE=${SOURCEDIR}
-GRAPHVIZ_MK := ${SOURCEDIR}/graphviz.mk
-GRAPHVIZ    := $(MAKE) -f "${GRAPHVIZ_MK}" SOURCE=${SOURCEDIR}
-DEMOS_MK    := ${SOURCEDIR}/demos.mk
-DEMOS       := $(MAKE) -f "${DEMOS_MK}" SOURCE=${SOURCEDIR}
-NOTEBOOK_MK := ${SOURCEDIR}/notebook.mk
-NOTEBOOK    := $(MAKE) -f "${NOTEBOOK_MK}" SOURCE=${SOURCEDIR}
-
-_CURRENT_PATH := ${PATH}
-_PROJ_DIR     := $(shell readlink -f ${CURDIR}/..)
-_LIBS_DIR     := $(shell readlink -f ${SOURCEDIR}/_libs)
-_SHIMS_DIR    := $(shell readlink -f ${SOURCEDIR}/_shims)
+DIAGRAMS_MK := diagrams.mk
+DIAGRAMS    := $(MAKE) -f "${DIAGRAMS_MK}"
 
-.EXPORT_ALL_VARIABLES:
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXLIVE    = sphinx-autobuild
+SOURCEDIR     = source
+BUILDDIR      = build
 
-PYTHONPATH = ${_PROJ_DIR}:${_LIBS_DIR}
-PATH       = ${_SHIMS_DIR}:${_CURRENT_PATH}
-NO_CONTENTS_BUILD = true
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 # Put it first so that "make" without argument is like "make help".
-.PHONY: help contents build html prod clean sourcedir builddir Makefile
-
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-contents:
+# Build & clean the documentation
+diagrams:
 	@$(DIAGRAMS) build
-	@$(GRAPHVIZ) build
-	@$(DEMOS) build
-	@$(NOTEBOOK) build
-build: html
-html: contents
+html: diagrams
 	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@touch "$(BUILDDIR)/html/.nojekyll"
-prod:
-	@NO_CONTENTS_BUILD='' $(SPHINXMULTIVERSION) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
-	@cp main_page.html "$(BUILDDIR)/html/index.html"
-	@touch "$(BUILDDIR)/html/.nojekyll"
-
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" ./source/**/*_zh.* $(SPHINXOPTS) $(O) -D master_doc=index_zh
+live: diagrams
+	@$(SPHINXLIVE) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+build: html
 clean:
 	@$(DIAGRAMS) clean
-	@$(GRAPHVIZ) clean
-	@$(DEMOS) clean
-	@$(NOTEBOOK) clean
 	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-sourcedir:
-	@echo $(shell readlink -f ${SOURCEDIR})
-builddir:
-	@echo $(shell readlink -f ${BUILDDIR}/html)
+.PHONY: help diagrams html build clean 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
+	@$(DIAGRAMS) build
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,60 @@
+# 🎨 Welcome to LightZero Docs
+
+[![Documentation Status](https://readthedocs.org/projects/lightzero-docs/badge/?version=latest)](https://lightzero-docs.readthedocs.io/en/latest/?badge=latest)
+
+[LightZero](https://arxiv.org/pdf/2310.08348.pdf) is a lightweight, efficient, and easy-to-understand open-source algorithm toolkit that combines Monte Carlo Tree Search (MCTS) and Deep Reinforcement Learning (RL).
+
+The LightZero documentation can be found [here](https://opendilab.github.io/LightZero/). It contains tutorials and the API reference.
+
+For those interested in customizing environments and algorithms, we provide relevant guides:
+
+- [Customize Environments](https://github.com/opendilab/LightZero/blob/main/docs/en/source//tutorials/envs/customize_envs.md)
+- [Customize Algorithms](https://github.com/opendilab/LightZero/blob/main/docs/en/source//tutorials/algos/customize_algos.md)
+- [How to Set Configuration Files?](https://github.com/opendilab/LightZero/blob/main/docs/en/source//tutorials/config/config.md)
+- [Logging and Monitoring System](https://github.com/opendilab/LightZero/blob/main/docs/en/source//tutorials/logs/logs.md)
+
+Should you have any questions, feel free to contact us for support.
+
+
+# ⚙️ Local Docs Generation
+```bash
+# step 1: install
+cd LightZero
+pip install -r requirements-doc.txt
+# step 2: compile docs
+cd LightZero/docs/source
+make live
+# step 3: open http://127.0.0.1:8000 in your browser, and explore it!
+```
+
+# 🌏 Citing LightZero-docs
+
+```latex
+@article{niu2024lightzero,
+  title={LightZero: A Unified Benchmark for Monte Carlo Tree Search in General Sequential Decision Scenarios},
+  author={Niu, Yazhe and Pu, Yuan and Yang, Zhenjie and Li, Xueyan and Zhou, Tong and Ren, Jiyuan and Hu, Shuai and Li, Hongsheng and Liu, Yu},
+  journal={Advances in Neural Information Processing Systems},
+  volume={36},
+  year={2024}
+}
+
+@article{pu2024unizero,
+  title={UniZero: Generalized and Efficient Planning with Scalable Latent World Models},
+  author={Pu, Yuan and Niu, Yazhe and Ren, Jiyuan and Yang, Zhenjie and Li, Hongsheng and Liu, Yu},
+  journal={arXiv preprint arXiv:2406.10667},
+  year={2024}
+}
+
+@article{xuan2024rezero,
+  title={ReZero: Boosting MCTS-based Algorithms by Backward-view and Entire-buffer Reanalyze},
+  author={Xuan, Chunyu and Niu, Yazhe and Pu, Yuan and Hu, Shuai and Liu, Yu and Yang, Jing},
+  journal={arXiv preprint arXiv:2404.16364},
+  year={2024}
+}
+```
+# Contact Us
+If you have any questions about documentation, please add a new issue or contact `opendilab@pjlab.org.cn`
+
+# License
+
+LightZero-Docs released under the Apache 2.0 license
diff --git a/docs/source/diagrams.mk → docs/diagrams.mk b/docs/source/diagrams.mk → docs/diagrams.mk
diff --git a/docs/main_page.html b/docs/main_page.html
diff --git a/docs/make.bat 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
+
+if "%1" == "" goto help
+
+%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.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/_static/css/style.css b/docs/source/_static/css/style.css
@@ -0,0 +1,6 @@
+.header-logo {
+    background-image: url("../../../../LightZero.png");
+    background-size: 180px 40px;
+    height: 40px;
+    width: 180px;
+}
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <link href="{{ pathto("_static/css/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}
diff --git a/docs/source/api_doc/agent/index.rst b/docs/source/api_doc/agent/index.rst
@@ -0,0 +1,22 @@
+Agent
+==========
+
+.. autoclass:: lzero.agent.alphazero.AlphaZeroAgent
+    :members:
+
+.. autoclass:: lzero.agent.muzero.MuZeroAgent
+    :members:
+
+.. autoclass:: lzero.agent.efficientzero.EfficientZeroAgent
+    :members:
+
+.. autoclass:: lzero.agent.gumbel_muzero.GumbelMuZeroAgent
+    :members:
+
+.. autoclass:: lzero.agent.sampled_efficientzero.SampledEfficientZeroAgent
+    :members:
+
+.. autoclass:: lzero.agent.sampled_alphazero.SampledAlphaZeroAgent
+    :members:
+
+
diff --git a/docs/source/api_doc/config/index.rst b/docs/source/api_doc/config/index.rst
@@ -1,7 +1,7 @@
-lzero.config
+Config
 =====================
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 2
 
-    meta
+    meta