docs: add autogenerated API documentation (#87)

.github/workflows/check-python.yaml

@@ -31,7 +31,7 @@ jobs:
       - name: Check documentation
         run: |
             set -o pipefail
-            poetry run make -C docs html SPHINXOPTS="-W --keep-going -n -E"
+            poetry run poe docs
 
   tests:
     runs-on: "ubuntu-latest"

.gitignore

@@ -3,4 +3,7 @@ __pycache__
 .DS_Store
 examples/**/*.trace
 # Sphinx documentation
-docs/_build/
+/docs/_build/
+# autogenerated doc
+/docs/apidocs/
+/docs/puyapy-stubs/

docs/api-puyapy.arc4.md

@@ -0,0 +1,4 @@
+```{autodoc2-object} puyapy.arc4
+    
+render_plugin = "myst"
+```

docs/api-puyapy.md

@@ -0,0 +1,4 @@
+```{autodoc2-object} puyapy
+    
+render_plugin = "myst"
+```

docs/api.md

@@ -0,0 +1,10 @@
+# API Reference
+
+```{toctree}
+---
+maxdepth: 4
+---
+
+api-puyapy
+api-puyapy.arc4
+```

docs/conf.py

@@ -15,21 +15,62 @@
 
 extensions = [
     "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
     "myst_parser",
+    "autodoc2",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# warning exclusions
+suppress_warnings = [
+    "myst.xref_missing",
+    "autodoc2.dup_item",
+]
+nitpick_ignore = [
+    ("py:class", "puyapy._T"),
+    ("py:class", "puyapy._P"),
+    ("py:class", "puyapy._R"),
+    ("py:class", "puyapy.arc4._T"),
+    ("py:class", "puyapy.arc4._TArrayItem"),
+    ("py:class", "puyapy.arc4._TTuple"),
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 # html_static_path = ["_static"]
 
 # -- Options for myst ---
 myst_enable_extensions = [
     "colon_fence",
     "fieldlist",
 ]
+
+# -- Options for autodoc2 ---
+autodoc2_packages = [
+    {
+        "path": "./puyapy-stubs",
+        "module": "puyapy",
+        "auto_mode": False,
+    },
+]
+autodoc2_docstring_parser_regexes = [
+    # this will render all docstrings as Markdown
+    (r".*", "myst"),
+]
+autodoc2_hidden_objects = [
+    "private",  # single-underscore methods, e.g. _private
+    "undoc",
+]
+autodoc2_class_inheritance = False
+autodoc2_module_all_regexes = [r"puyapy"]
+autodoc2_render_plugin = "myst"
+autodoc2_sort_names = True
+autodoc2_index_template = None

docs/index.md

@@ -135,4 +135,5 @@ hidden: true
 
 language_guide
 principles
+api
 ```