feat(docs): add napoleon, autodoc, viewcode (#683)

project/docs/conf.py.jinja

@@ -1,34 +1,89 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# For the full list of built-in configuration values, see the documentation:
+# 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
+from pathlib import Path
+from typing import Any
+
+from sphinx.application import Sphinx
+from sphinx.ext import apidoc
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-# Project information
 project = "{{ project_name }}"
 copyright = "{{ copyright_year }}, {{ full_name }}"
 author = "{{ full_name }}"
 release = "0.0.0"
 
-# General configuration
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#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 = [
     "myst_parser",
+    "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
 ]
+napoleon_google_docstring = False
 
 # The suffix of source filenames.
 source_suffix = [
     ".rst",
     ".md",
 ]
+
+# Add any paths that contain templates here, relative to this directory.
 templates_path = [
     "_templates",
 ]
+
+# 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",
 ]
 
-# Options for HTML output
+
+# -- 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 = "furo"
+
+# 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"]
+
+
+# -- Automatically run sphinx-apidoc -----------------------------------------
+
+
+def run_apidoc(_: Any) -> None:
+    """Run sphinx-apidoc."""
+    docs_path = Path(__file__).parent
+    module_path = docs_path.parent / "src" / "{{ package_name }}"
+
+    apidoc.main(
+        [
+            "--force",
+            "--module-first",
+            "-o",
+            docs_path.as_posix(),
+            module_path.as_posix(),
+        ]
+    )
+
+
+def setup(app: Sphinx) -> None:
+    """Setup sphinx."""
+    app.connect("builder-inited", run_apidoc)

project/docs/index.md.jinja

@@ -19,6 +19,13 @@ changelog
 contributing
 ```
 
+```{toctree}
+:caption: API Reference
+:maxdepth: 2
+
+{{ package_name }}
+```
+
 ```{include} ../README.md
 
 ```