Documentation update: jupyter-book running on ReadTheDocs including tutorial notebooks

This commit is contained in:
carlocagnetta 2023-11-10 13:46:49 +01:00 committed by Michael Panchenko
parent 6df56161f5
commit 8f0c62ace3
43 changed files with 1113 additions and 1433 deletions

5
.gitignore vendored
View File

@ -153,8 +153,9 @@ videos/
# might be needed for IDE plugins that can't read ruff config
.flake8
docs/notebooks/_build/
docs/conf.py
# temporary scripts (for ad-hoc testing), temp folder
/temp
/temp*.py
docs/notebooks/_build/

View File

@ -13,12 +13,16 @@ build:
jobs:
pre_build:
- pip install .
# Generate the Sphinx configuration for this Jupyter Book, so it builds.
- "jupyter-book config sphinx notebooks/"
post_install:
- poetry install --with dev
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# sphinx:
# configuration: docs/conf.py
# We recommend specifying your dependencies to enable reproducible builds:
# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- requirements: docs/requirements.txt
- poetry

View File

@ -9,11 +9,11 @@
#######################################################################################
# Book settings
title : Tutorials of Tianshou # The title of the book. Will be placed in the left navbar.
author : tianshou developers # The author of the book
copyright : "" # Copyright year to be placed in the footer
author : Tianshou contributors # The author of the book
copyright : "2020, Tianshou contributors." # Copyright year to be placed in the footer
logo : _static/images/tianshou-logo.png # A path to the book logo
# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")
exclude_patterns : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"]
exclude_patterns : ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build']
# Auto-exclude files not in the toc
only_build_toc_files : false
@ -71,6 +71,10 @@ html:
latex:
latex_engine : pdflatex # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
use_jupyterbook_latex : true # use sphinx-jupyterbook-latex for pdf builds as default
targetname : book.tex
# Add a bibtex file so that we can create citations
bibtex_bibfiles:
- refs.bib
#######################################################################################
# Launch button settings

40
docs/_toc.yml Normal file
View File

@ -0,0 +1,40 @@
# Table of contents
# Learn more at https://jupyterbook.org/customize/toc.html
format: jb-book
root: index
parts:
- caption: Get started!
chapters:
- file: notebooks/intro
- file: tutorials/get_started
- file: notebooks/L0_overview
- file: notebooks/L1_Batch
- file: notebooks/L2_Buffer
- file: notebooks/L3_Vectorized__Environment
- file: notebooks/L4_Policy
- file: notebooks/L5_Collector
- file: notebooks/L6_Trainer
- file: notebooks/L7_Experiment
- caption: Tutorials
chapters:
- file: tutorials/dqn
- file: tutorials/concepts
- file: tutorials/batch
- file: tutorials/tictactoe
- file: tutorials/logger
- file: tutorials/benchmark
- file: tutorials/cheatsheet
- caption: API
chapters:
- file: api/tianshou.data.rst
- file: api/tianshou.env.rst
- file: api/tianshou.policy.rst
- file: api/tianshou.trainer.rst
- file: api/tianshou.exploration.rst
- file: api/tianshou.utils.rst
- file: api/tianshou.highlevel/index.rst
- caption: Community
chapters:
- file: contributing
- file: contributor

View File

@ -1,142 +0,0 @@
tianshou.data
=============
Batch
-----
.. autoclass:: tianshou.data.Batch
:members:
:undoc-members:
:show-inheritance:
Buffer
------
ReplayBuffer
~~~~~~~~~~~~
.. autoclass:: tianshou.data.ReplayBuffer
:members:
:undoc-members:
:show-inheritance:
PrioritizedReplayBuffer
~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.PrioritizedReplayBuffer
:members:
:undoc-members:
:show-inheritance:
HERReplayBuffer
~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.HERReplayBuffer
:members:
:undoc-members:
:show-inheritance:
ReplayBufferManager
~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.ReplayBufferManager
:members:
:undoc-members:
:show-inheritance:
PrioritizedReplayBufferManager
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.PrioritizedReplayBufferManager
:members:
:undoc-members:
:show-inheritance:
HERReplayBufferManager
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.HERReplayBufferManager
:members:
:undoc-members:
:show-inheritance:
VectorReplayBuffer
~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.VectorReplayBuffer
:members:
:undoc-members:
:show-inheritance:
PrioritizedVectorReplayBuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.PrioritizedVectorReplayBuffer
:members:
:undoc-members:
:show-inheritance:
HERVectorReplayBuffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.HERVectorReplayBuffer
:members:
:undoc-members:
:show-inheritance:
CachedReplayBuffer
~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.CachedReplayBuffer
:members:
:undoc-members:
:show-inheritance:
Collector
---------
Collector
~~~~~~~~~
.. autoclass:: tianshou.data.Collector
:members:
:undoc-members:
:show-inheritance:
AsyncCollector
~~~~~~~~~~~~~~
.. autoclass:: tianshou.data.AsyncCollector
:members:
:undoc-members:
:show-inheritance:
Utils
-----
to_numpy
~~~~~~~~
.. autofunction:: tianshou.data.to_numpy
to_torch
~~~~~~~~
.. autofunction:: tianshou.data.to_torch
to_torch_as
~~~~~~~~~~~
.. autofunction:: tianshou.data.to_torch_as
SegmentTree
~~~~~~~~~~~
.. autoclass:: tianshou.data.SegmentTree
:members:
:undoc-members:
:show-inheritance:

View File

@ -1,122 +0,0 @@
tianshou.env
============
VectorEnv
---------
BaseVectorEnv
~~~~~~~~~~~~~
.. autoclass:: tianshou.env.BaseVectorEnv
:members:
:undoc-members:
:show-inheritance:
DummyVectorEnv
~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.DummyVectorEnv
:members:
:undoc-members:
:show-inheritance:
SubprocVectorEnv
~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.SubprocVectorEnv
:members:
:undoc-members:
:show-inheritance:
ShmemVectorEnv
~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.ShmemVectorEnv
:members:
:undoc-members:
:show-inheritance:
RayVectorEnv
~~~~~~~~~~~~
.. autoclass:: tianshou.env.RayVectorEnv
:members:
:undoc-members:
:show-inheritance:
Wrapper
-------
ContinuousToDiscrete
~~~~~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.ContinuousToDiscrete
:members:
:undoc-members:
:show-inheritance:
VectorEnvWrapper
~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.VectorEnvWrapper
:members:
:undoc-members:
:show-inheritance:
VectorEnvNormObs
~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.VectorEnvNormObs
:members:
:undoc-members:
:show-inheritance:
Worker
------
EnvWorker
~~~~~~~~~
.. autoclass:: tianshou.env.worker.EnvWorker
:members:
:undoc-members:
:show-inheritance:
DummyEnvWorker
~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.worker.DummyEnvWorker
:members:
:undoc-members:
:show-inheritance:
SubprocEnvWorker
~~~~~~~~~~~~~~~~
.. autoclass:: tianshou.env.worker.SubprocEnvWorker
:members:
:undoc-members:
:show-inheritance:
RayEnvWorker
~~~~~~~~~~~~
.. autoclass:: tianshou.env.worker.RayEnvWorker
:members:
:undoc-members:
:show-inheritance:
Utils
-----
PettingZooEnv
~~~~~~~~~~~~~
.. autoclass:: tianshou.env.PettingZooEnv
:members:
:undoc-members:
:show-inheritance:

View File

@ -1,7 +0,0 @@
tianshou.exploration
====================
.. automodule:: tianshou.exploration
:members:
:undoc-members:
:show-inheritance:

View File

@ -0,0 +1,6 @@
agent
=====
.. automodule:: tianshou.highlevel.agent
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
config
======
.. automodule:: tianshou.highlevel.config
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
env
===
.. automodule:: tianshou.highlevel.env
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
experiment
==========
.. automodule:: tianshou.highlevel.experiment
:members:
:undoc-members:

View File

@ -0,0 +1,11 @@
tianshou.highlevel
==================
.. automodule:: tianshou.highlevel
:members:
:undoc-members:
.. toctree::
:glob:
*

View File

@ -0,0 +1,6 @@
logger
======
.. automodule:: tianshou.highlevel.logger
:members:
:undoc-members:

View File

@ -0,0 +1,11 @@
module
======
.. automodule:: tianshou.highlevel.module
:members:
:undoc-members:
.. toctree::
:glob:
module/*

View File

@ -0,0 +1,6 @@
actor
=====
.. automodule:: tianshou.highlevel.module.actor
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
core
====
.. automodule:: tianshou.highlevel.module.core
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
critic
======
.. automodule:: tianshou.highlevel.module.critic
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
intermediate
============
.. automodule:: tianshou.highlevel.module.intermediate
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
module\_opt
===========
.. automodule:: tianshou.highlevel.module.module_opt
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
special
=======
.. automodule:: tianshou.highlevel.module.special
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
optim
=====
.. automodule:: tianshou.highlevel.optim
:members:
:undoc-members:

View File

@ -0,0 +1,11 @@
params
======
.. automodule:: tianshou.highlevel.params
:members:
:undoc-members:
.. toctree::
:glob:
params/*

View File

@ -0,0 +1,6 @@
alpha
=====
.. automodule:: tianshou.highlevel.params.alpha
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
dist\_fn
========
.. automodule:: tianshou.highlevel.params.dist_fn
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
env\_param
==========
.. automodule:: tianshou.highlevel.params.env_param
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
lr\_scheduler
=============
.. automodule:: tianshou.highlevel.params.lr_scheduler
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
noise
=====
.. automodule:: tianshou.highlevel.params.noise
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
policy\_params
==============
.. automodule:: tianshou.highlevel.params.policy_params
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
policy\_wrapper
===============
.. automodule:: tianshou.highlevel.params.policy_wrapper
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
persistence
===========
.. automodule:: tianshou.highlevel.persistence
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
trainer
=======
.. automodule:: tianshou.highlevel.trainer
:members:
:undoc-members:

View File

@ -0,0 +1,6 @@
world
=====
.. automodule:: tianshou.highlevel.world
:members:
:undoc-members:

View File

@ -1,176 +0,0 @@
tianshou.policy
===============
Base
----
.. autoclass:: tianshou.policy.BasePolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.RandomPolicy
:members:
:undoc-members:
:show-inheritance:
Model-free
----------
DQN Family
~~~~~~~~~~
.. autoclass:: tianshou.policy.DQNPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.BranchingDQNPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.C51Policy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.RainbowPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.QRDQNPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.IQNPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.FQFPolicy
:members:
:undoc-members:
:show-inheritance:
On-policy
~~~~~~~~~
.. autoclass:: tianshou.policy.PGPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.NPGPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.A2CPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.TRPOPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.PPOPolicy
:members:
:undoc-members:
:show-inheritance:
Off-policy
~~~~~~~~~~
.. autoclass:: tianshou.policy.DDPGPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.TD3Policy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.SACPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.REDQPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.DiscreteSACPolicy
:members:
:undoc-members:
:show-inheritance:
Imitation
---------
.. autoclass:: tianshou.policy.ImitationPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.BCQPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.CQLPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.TD3BCPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.DiscreteBCQPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.DiscreteCQLPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.DiscreteCRRPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.GAILPolicy
:members:
:undoc-members:
:show-inheritance:
Model-based
-----------
.. autoclass:: tianshou.policy.PSRLPolicy
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: tianshou.policy.ICMPolicy
:members:
:undoc-members:
:show-inheritance:
Multi-agent
-----------
.. autoclass:: tianshou.policy.MultiAgentPolicyManager
:members:
:undoc-members:
:show-inheritance:

View File

@ -1,36 +0,0 @@
tianshou.trainer
================
On-policy
---------
.. autoclass:: tianshou.trainer.OnpolicyTrainer
:members:
:undoc-members:
:show-inheritance:
Off-policy
----------
.. autoclass:: tianshou.trainer.OffpolicyTrainer
:members:
:undoc-members:
:show-inheritance:
Offline
-------
.. autoclass:: tianshou.trainer.OfflineTrainer
:members:
:undoc-members:
:show-inheritance:
utils
-----
.. autofunction:: tianshou.trainer.test_episode
.. autofunction:: tianshou.trainer.gather_info

View File

@ -1,35 +0,0 @@
tianshou.utils
==============
.. automodule:: tianshou.utils
:members:
:undoc-members:
:show-inheritance:
Pre-defined Networks
--------------------
Common
~~~~~~
.. automodule:: tianshou.utils.net.common
:members:
:undoc-members:
:show-inheritance:
Discrete
~~~~~~~~
.. automodule:: tianshou.utils.net.discrete
:members:
:undoc-members:
:show-inheritance:
Continuous
~~~~~~~~~~
.. automodule:: tianshou.utils.net.continuous
:members:
:undoc-members:
:show-inheritance:

View File

@ -1,100 +0,0 @@
# 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('.'))
import sphinx_rtd_theme
import tianshou
# Get the version string
version = tianshou.__version__
# -- Project information -----------------------------------------------------
project = "Tianshou"
copyright = "2020, Tianshou contributors."
author = "Tianshou contributors"
# The full version, including alpha/beta/rc tags
release = version
# -- 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.doctest",
"sphinx.ext.intersphinx",
"sphinx.ext.coverage",
# 'sphinx.ext.imgmath',
"sphinx.ext.mathjax",
"sphinx.ext.ifconfig",
"sphinx.ext.viewcode",
"sphinx.ext.githubpages",
"sphinxcontrib.bibtex",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
source_suffix = [".rst"]
master_doc = "index"
# 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"]
autodoc_default_options = {"special-members": "__len__, __call__, __getitem__, __setitem__"}
autodoc_member_order = "bysource"
bibtex_bibfiles = ["refs.bib"]
# -- 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"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# 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_logo = "_static/images/tianshou-logo.png"
def setup(app):
app.add_js_file("https://cdn.jsdelivr.net/npm/vega@5.20.2")
app.add_js_file("https://cdn.jsdelivr.net/npm/vega-lite@5.1.0")
app.add_js_file("https://cdn.jsdelivr.net/npm/vega-embed@6.17.0")
app.add_js_file("js/copybutton.js")
app.add_js_file("js/benchmark.js")
app.add_css_file("css/style.css")
# -- Extension configuration -------------------------------------------------
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
# intersphinx_mapping = {'https://docs.python.org/3/': None}
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
# todo_include_todos = False

View File

@ -1,4 +1,4 @@
Contributor
Contributors
===========
We always welcome contributions to help make Tianshou better. Below are an incomplete list of our contributors (find more on `this page <https://github.com/thu-ml/tianshou/graphs/contributors>`_).

View File

@ -93,12 +93,26 @@ If no error occurs, you have successfully installed Tianshou.
Tianshou is still under development, you can also check out the documents in stable version through `tianshou.readthedocs.io/en/stable/ <https://tianshou.readthedocs.io/en/stable/>`_.
.. toctree::
:maxdepth: 2
:caption: Get started:
tutorials/get_started
notebooks/intro
notebooks/L0_overview
notebooks/L1_Batch
notebooks/L2_Buffer
notebooks/L3_Vectorized__Environment
notebooks/L4_Policy
notebooks/L5_Collector
notebooks/L6_Trainer
notebooks/L7_Experiment
.. toctree::
:maxdepth: 1
:caption: Tutorials
tutorials/get_started
tutorials/dqn
tutorials/concepts
tutorials/batch

View File

@ -1,7 +0,0 @@
# Table of contents
# Learn more at https://jupyterbook.org/customize/toc.html
format: jb-book
root: intro
chapters:
- glob: L*

View File

@ -8,3 +8,5 @@ torch
tqdm
protobuf
pettingzoo
nbsphinx
recommonmark

View File

@ -188,6 +188,8 @@ MLP
backpropagation
dataclass
superset
subtype
subdirectory
picklable
ShmemVectorEnv
Github

1655
poetry.lock generated

File diff suppressed because it is too large Load Diff

View File

@ -63,9 +63,11 @@ envpool = ["envpool"]
optional = true
[tool.poetry.group.dev.dependencies]
black = { version = "^23.7.0", extras = ["jupyter"] }
docstring-parser = "^0.15"
jinja2 = "*"
jupyter = "^1.0.0"
jupyter-book = "^0.15.1"
jsonargparse = "^4.24.1"
mypy = "^1.4.1"
nbstripout = "^0.6.1"
# networkx is used in a test
@ -86,6 +88,8 @@ sphinx_rtd_theme = "*"
sphinxcontrib-bibtex = "*"
sphinxcontrib-spelling = "^8.0.0"
wandb = "^0.12.0"
nbsphinx = "^0.9.3"
recommonmark = "^0.7.1"
[tool.mypy]
allow_redefinition = true
@ -152,7 +156,6 @@ max-complexity = 20
"docs/**" = ["D103"]
"examples/**" = ["D103"]
[tool.poetry_bumpversion.file."tianshou/__init__.py"]
[tool.poetry-sort]
@ -171,8 +174,9 @@ _poetry_install_sort_plugin = "poetry self add poetry-plugin-sort"
_poetry_sort = "poetry sort"
_clean-nbs = "nbstripout notebooks/*"
format = ["_black_format", "_ruff_format", "_poetry_install_sort_plugin", "_poetry_sort", "_clean-nbs"]
_spellcheck = "sphinx-build -W -b spelling docs docs/_build"
_doc_build = "sphinx-build -W -b html docs docs/_build"
_autogen_rst = "python docs/autogen_rst.py"
_spellcheck = "sphinx-build -b spelling docs docs/_build"
_doc_build = "sphinx-build -b html docs docs/_build"
doc-clean = "rm -rf docs/_build"
doc-build = ["_spellcheck", "_doc_build"]
type-check = "mypy tianshou"