Setup jupyter-book

notebooks/_config.yml

@@ -0,0 +1,42 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Tutorials of Tianshou
+author: tianshou developers
+logo: _static/images/tianshou-logo.png
+execute:
+  timeout: -1
+
+sphinx:
+  config:
+    mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+    mathjax3_config:
+      loader: { load: [ '[tex]/configmacros' ] }
+      tex:
+        packages: { '[+]': [ 'configmacros' ] }
+        macros:
+          vect: ["{\\mathbf{\\boldsymbol{#1}} }", 1]
+          E: "{\\mathbb{E}}"
+          P: "{\\mathbb{P}}"
+          R: "{\\mathbb{R}}"
+          abs: ["{\\left| #1 \\right|}", 1]
+          simpl: ["{\\Delta^{#1} }", 1]
+          amax: "{\\text{argmax}}"
+
+
+# Parse and render settings
+parse:
+  myst_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    - amsmath
+    - colon_fence
+    # - deflist
+    - dollarmath
+    # - html_admonition
+    # - html_image
+    - linkify
+    # - replacements
+    # - smartquotes
+    - substitution
+    - tasklist
+  myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
+  myst_dmath_double_inline: true  # Allow display math ($$) within an inline context

notebooks/_toc.yml

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

notebooks/intro.md

@@ -0,0 +1,3 @@
+# Tianshou Tutorials
+
+Placeholder for intro

pyproject.toml

@@ -62,12 +62,12 @@ envpool = ["envpool"]
 [tool.poetry.group.dev]
 optional = true
 [tool.poetry.group.dev.dependencies]
-black = "^23.7.0"
-docstring-parser = "^0.15"
+black = { version = "^23.7.0", extras = ["jupyter"] }
 jinja2 = "*"
-jsonargparse = "^4.24.1"
 jupyter = "^1.0.0"
+jupyter-book = "^0.15.1"
 mypy = "^1.4.1"
+nbstripout = "^0.6.1"
 # networkx is used in a test
 networkx = "*"
 poethepoet = "^0.20.0"
@@ -105,7 +105,7 @@ warn_redundant_casts = true
 warn_unreachable = true
 warn_unused_configs = true
 warn_unused_ignores = true
-exclude = "^build/|^docs/|^tianshou/utils/(string|logging).py|^temp*.py"
+exclude = "^build/|^docs/"
 
 [tool.doc8]
 max-line-length = 1000
@@ -125,11 +125,8 @@ ignore = [
     "B008", # do not perform function calls in argument defaults. we do this sometimes
     "B011", # assert false. we don't use python -O
     "B028", # we don't need explicit stacklevel for warnings
-    "D100", "D101", "D102", "D104", "D105", "D107", "D203", "D213", "D401", "D402", "D106", "D205",  # docstring stuff
-    "G004",   # logging (no f-strings)
-    "RUF012",  # disallows mutable class variables unless annotated
+    "D100", "D101", "D102", "D104", "D105", "D107", "D203", "D213", "D401", "D402", # docstring stuff
     "DTZ005", # we don't need that
-    "RET505",  # sacrifices visual discernability of control flow paths for brevity (regarding return statements)
     # remaining rules from https://github.com/psf/black/blob/main/.flake8 (except W503)
     # this is a simplified version of config, making vscode plugin happy
     "E402", "E501", "E701", "E731", "C408", "E203"
@@ -144,7 +141,6 @@ extend-fixable = [
     "F401", # unused import
     "B905", # bugbear
 ]
-ignore-init-module-imports = true  # without this, "unused" imports in __init__ will be auto-removed, breaking imports
 
 target-version = "py311"
 
@@ -172,11 +168,11 @@ _black_format = "black ."
 _ruff_format = "ruff --fix ."
 lint = ["_black_check", "_ruff_check"]
 _poetry_install_sort_plugin = "poetry self add poetry-plugin-sort"
-_poery_sort = "poetry sort"
-format = ["_black_format", "_ruff_format", "_poetry_install_sort_plugin", "_poery_sort"]
-_autogen_rst = "python docs/autogen_rst.py"
+_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"
 doc-clean = "rm -rf docs/_build"
-doc-build = ["_autogen_rst", "_spellcheck", "_doc_build"]
+doc-build = ["_spellcheck", "_doc_build"]
 type-check = "mypy tianshou"