docs: Generate documentation for method parameters

docs/CONTRIBUTING.md

@@ -104,14 +104,10 @@ ReadtheDocs.org. When a push is detected by readthedocs.org, they automatically
 and republish the docs. ReadtheDocs is also version aware, so it retains prior and unreleased
 versions of the docs for us.
 
-To build the docs:
+To build the docs and live-reload them locally:
 
 ```bash
-# Build docs
-nox -rs docs
-
-# Open in the local browser:
-open build/index.html
+nox -rs docs-serve
 ```
 
 Sphinx will automatically generate class stubs, so be sure to `git add` them.

docs/conf.py

@@ -51,9 +51,9 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# Show typehints in the signature
-# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints
-autodoc_typehints = "signature"
+# Show typehints in the description, along with parameter descriptions
+autodoc_typehints = "description"
+autodoc_class_signature = "separated"
 
 # -- Options for HTML output -------------------------------------------------
 

noxfile.py

@@ -126,3 +126,25 @@ def docs(session: Session) -> None:
         shutil.rmtree(build_dir)
 
     session.run("sphinx-build", *args)
+
+
+@session(name="docs-serve", python=main_python_version)
+def docs_serve(session: Session) -> None:
+    """Build the documentation."""
+    args = session.posargs or [
+        "--open-browser",
+        "--watch",
+        ".",
+        "--ignore",
+        "**/.nox/*",
+        "docs",
+        "build",
+        "-W",
+    ]
+    session.install(".[docs]")
+
+    build_dir = Path("build")
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
+
+    session.run("sphinx-autobuild", *args)

pyproject.toml

@@ -58,9 +58,16 @@ sphinx = {version = ">=4.5,<6.0", optional = true}
 sphinx-rtd-theme = {version = ">=0.5.2,<1.1.0", optional = true}
 sphinx-copybutton = {version = ">=0.3.1,<0.6.0", optional = true}
 myst-parser = {version = ">=0.17.2,<0.19.0", optional = true}
+sphinx-autobuild = {version = "^2021.3.14", optional = true}
 
 [tool.poetry.extras]
-docs = ["sphinx", "sphinx-rtd-theme", "sphinx-copybutton", "myst-parser"]
+docs = [
+    "sphinx",
+    "sphinx-rtd-theme",
+    "sphinx-copybutton",
+    "myst-parser",
+    "sphinx-autobuild",
+]
 
 [tool.poetry.dev-dependencies]
 # snowflake-connector-python = "2.0.4" # Removed: Too many version conflicts!