From 2c419594ea9defa93410fe13acac66f0d1091778 Mon Sep 17 00:00:00 2001
From: Elias Bonnici <elias.bonnici@yubico.com>
Date: Mon, 9 Dec 2024 14:09:03 +0100
Subject: [PATCH] Use `sphinx-autoapi` over `sphinx-autodoc`

---
 .github/workflows/build.yml   |  2 +-
 docs/conf.py                  | 17 ++++++++--
 docs/index.rst                |  4 ++-
 docs/rst/yubihsm.backends.rst | 29 ----------------
 docs/rst/yubihsm.rst          | 62 -----------------------------------
 pyproject.toml                |  6 ++--
 6 files changed, 22 insertions(+), 98 deletions(-)
 delete mode 100644 docs/rst/yubihsm.backends.rst
 delete mode 100644 docs/rst/yubihsm.rst

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index f038154..67d2f28 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -130,7 +130,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: 3.12
 
       - name: Install python dependencies
         run: |
diff --git a/docs/conf.py b/docs/conf.py
index df5d624..0b80d8d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,13 +47,15 @@ def get_version():
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx_autodoc_typehints",
+    "autoapi.extension",
+    "sphinx.ext.autodoc.typehints",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
 ]
 
+autodoc_typehints = "description"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -189,3 +191,14 @@ def get_version():
     "python": ("https://docs.python.org/", None),
     "cryptography": ("https://cryptography.io/en/latest/", None),
 }
+
+# Custom config
+autoapi_dirs = ["../yubihsm"]
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "special-members",
+    "imported-members",
+]
diff --git a/docs/index.rst b/docs/index.rst
index 676d783..6cdc775 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,7 +9,9 @@ Welcome to python-yubihsm's documentation!
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
-   
+
+   autoapi/index
+
 
 Indices and tables
 ==================
diff --git a/docs/rst/yubihsm.backends.rst b/docs/rst/yubihsm.backends.rst
deleted file mode 100644
index 117563f..0000000
--- a/docs/rst/yubihsm.backends.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-yubihsm.backends package
-========================
-
-Submodules
-----------
-
-yubihsm.backends.http module
-----------------------------
-
-.. automodule:: yubihsm.backends.http
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-yubihsm.backends.usb module
----------------------------
-
-.. automodule:: yubihsm.backends.usb
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: yubihsm.backends
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/rst/yubihsm.rst b/docs/rst/yubihsm.rst
deleted file mode 100644
index d8ef1ad..0000000
--- a/docs/rst/yubihsm.rst
+++ /dev/null
@@ -1,62 +0,0 @@
-yubihsm package
-===============
-
-Subpackages
------------
-
-.. toctree::
-   
-   yubihsm.backends
-
-Submodules
-----------
-
-yubihsm.core module
--------------------
-
-.. automodule:: yubihsm.core
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-yubihsm.defs module
--------------------
-
-.. automodule:: yubihsm.defs
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-yubihsm.exceptions module
--------------------------
-
-.. automodule:: yubihsm.exceptions
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-yubihsm.objects module
-----------------------
-
-.. automodule:: yubihsm.objects
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :exclude-members: int_to_bytes, int_from_bytes
-
-yubihsm.utils module
---------------------
-
-.. automodule:: yubihsm.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: yubihsm
-    :members:
-    :undoc-members:
-    :show-inheritance:
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index a390a40..e915797 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,9 +33,9 @@ usb = ["pyusb"]
 
 [tool.poetry.dev-dependencies]
 pytest = "^8.0"
-Sphinx = {version = "^7.1", python = ">=3.8"}
-sphinx-rtd-theme = {version = "^1.2.2", python = ">=3.8"}
-sphinx-autodoc-typehints = {version = "^1.2.4", python = ">=3.8"}
+Sphinx = {version = "^8.1", python = ">=3.10"}
+sphinx-rtd-theme = {version = "^3.0.1", python = ">=3.10"}
+sphinx-autoapi = {version = "^3.3.3", python = ">=3.10"}
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]