fix: style tweak for auto api

docs/conf.py

@@ -23,6 +23,7 @@
 # -- General configuration ---
 
 extensions = [
+    "autoapi.extension",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
@@ -62,6 +63,9 @@
     "sphinxdocs": ("https://www.sphinx-doc.org/en/master/%s", "%s"),
 }
 
+autoapi_dirs = ["src"]
+autoapi_add_toctree_entry = False
+
 add_module_names = False
 
 # -- Options for HTML output ---

docs/index.rst

@@ -76,3 +76,9 @@ Explore
          :titlesonly:
 
          demo/*
+
+.. toctree::
+   :hidden:
+   :caption: API demo
+
+   autoapi/api/index

docs/readthedocs.txt

@@ -1,6 +1,8 @@
 alabaster==0.7.13 ; python_version >= "3.8" and python_version < "3.9"
 alabaster==0.7.16 ; python_version >= "3.9" and python_version < "3.10"
 alabaster==1.0.0 ; python_version >= "3.10" and python_version < "4.0"
+astroid==3.2.4 ; python_version >= "3.8" and python_full_version < "3.9.0"
+astroid==3.3.5 ; python_full_version >= "3.9.0" and python_version < "4.0"
 babel==2.16.0 ; python_version >= "3.8" and python_version < "4.0"
 beautifulsoup4==4.12.3 ; python_version >= "3.8" and python_version < "4.0"
 certifi==2024.8.30 ; python_version >= "3.8" and python_version < "4.0"
@@ -13,15 +15,16 @@ imagesize==1.4.1 ; python_version >= "3.8" and python_version < "4.0"
 importlib-metadata==8.5.0 ; python_version >= "3.8" and python_version < "3.10"
 jinja2==3.1.4 ; python_version >= "3.8" and python_version < "4.0"
 livereload==2.7.0 ; python_version >= "3.8" and python_version < "4.0"
-markupsafe==2.1.5 ; python_version >= "3.8" and python_version < "3.9"
-markupsafe==3.0.2 ; python_version >= "3.9" and python_version < "4.0"
+markupsafe==2.1.5 ; python_version >= "3.8" and python_version < "4.0"
 packaging==24.1 ; python_version >= "3.8" and python_version < "4.0"
 pygments==2.18.0 ; python_version >= "3.8" and python_version < "4.0"
 python-dotenv==1.0.1 ; python_version >= "3.8" and python_version < "4.0"
 pytz==2024.2 ; python_version >= "3.8" and python_version < "3.9"
+pyyaml==6.0.2 ; python_version >= "3.8" and python_version < "4.0"
 requests==2.32.3 ; python_version >= "3.8" and python_version < "4.0"
 snowballstemmer==2.2.0 ; python_version >= "3.8" and python_version < "4.0"
 soupsieve==2.6 ; python_version >= "3.8" and python_version < "4.0"
+sphinx-autoapi==3.3.3 ; python_version >= "3.8" and python_version < "4.0"
 sphinx-autobuild==2021.3.14 ; python_version >= "3.8" and python_version < "4.0"
 sphinx-design==0.5.0 ; python_version >= "3.8" and python_version < "3.9"
 sphinx-design==0.6.1 ; python_version >= "3.9" and python_version < "3.13"
@@ -41,7 +44,9 @@ sphinxcontrib-qthelp==1.0.3 ; python_version >= "3.8" and python_version < "3.9"
 sphinxcontrib-qthelp==2.0.0 ; python_version >= "3.9" and python_version < "4.0"
 sphinxcontrib-serializinghtml==1.1.5 ; python_version >= "3.8" and python_version < "3.9"
 sphinxcontrib-serializinghtml==2.0.0 ; python_version >= "3.9" and python_version < "4.0"
+stdlib-list==0.10.0 ; python_version >= "3.8" and python_version < "3.10"
 tomli==2.0.2 ; python_version >= "3.9" and python_version < "3.11"
 tornado==6.4.1 ; python_version >= "3.8" and python_version < "4.0"
+typing-extensions==4.12.2 ; python_version >= "3.8" and python_full_version < "3.9.0"
 urllib3==2.2.3 ; python_version >= "3.8" and python_version < "4.0"
 zipp==3.20.2 ; python_version >= "3.8" and python_version < "3.10"

docs/src/api.py

@@ -0,0 +1,41 @@
+"""A module for demonstrating how styles for docs produced by sphinx-autoapi look like."""
+
+from __future__ import annotations
+
+
+def prompt(message: str, default: str | None = None) -> str | None:
+    """Prompt the user for a value.
+
+    Parameters
+    ----------
+    message: str
+        The message to prompt the user with.
+    default: str | None
+        The default value, by default None.
+
+    Returns:
+    --------
+    str | None
+        The value entered by the user or the default value,
+        if the user didn't enter anything.
+    """
+    text = f"{message} [{default}]" if default else message
+    return input(text).strip() or default
+
+
+def add(a: int, b: int) -> int:
+    """Returns the sum of two numbers.
+
+    Parameters
+    ----------
+    a: int
+        The first number.
+    b: int
+        The second number.
+
+    Returns:
+    --------
+    int
+        The sum of a and b.
+    """
+    return a + b

pyproject.toml

@@ -41,6 +41,7 @@ sphinx-design = [
 ]
 sphinx-docsearch = "*"
 python-dotenv = "*"
+sphinx-autoapi = "^3.3.3"
 
 [tool.poetry.group.dev]
 optional = true