docs: switch from autodoc to autoapi

mdtanker · Feb 22, 2024 · e182bac · e182bac
1 parent d20c603
commit e182bac
Show file tree

Hide file tree

Showing 16 changed files with 26 additions and 118 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -6,10 +6,11 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "mambaforge-22.9"
+    python: "3.11"
+    # python: "mambaforge-22.9"
 
 sphinx:
   configuration: docs/conf.py
 
-conda:
-  environment: env/RTD_env.yml
+# conda:
+#   environment: env/RTD_env.yml
diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t
diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t
diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,5 @@
+# API Reference
+
+```{toctree}
+autoapi/invert4geom/index
+```
diff --git a/docs/api/invert4geom.cross_validation.rst b/docs/api/invert4geom.cross_validation.rst
diff --git a/docs/api/invert4geom.inversion.rst b/docs/api/invert4geom.inversion.rst
diff --git a/docs/api/invert4geom.optimization.rst b/docs/api/invert4geom.optimization.rst
diff --git a/docs/api/invert4geom.plotting.rst b/docs/api/invert4geom.plotting.rst
diff --git a/docs/api/invert4geom.regional.rst b/docs/api/invert4geom.regional.rst
diff --git a/docs/api/invert4geom.rst b/docs/api/invert4geom.rst
diff --git a/docs/api/invert4geom.synthetic.rst b/docs/api/invert4geom.synthetic.rst
diff --git a/docs/api/invert4geom.utils.rst b/docs/api/invert4geom.utils.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -8,16 +8,15 @@
 version = release = invert4geom.__version__
 extensions = [
     "sphinx.ext.napoleon",
-    "sphinx.ext.autodoc",
+    "autoapi.extension",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
-    "sphinx_autodoc_typehints",
+    "sphinx.ext.autodoc",
     "sphinx_copybutton",
     "myst_parser",
     "sphinx_design",
     "nbsphinx",
     "sphinx.ext.viewcode",
-    # "sphinx.ext.autosummary",
 ]
 source_suffix = [".rst", ".md"]
 exclude_patterns = [
@@ -88,6 +87,10 @@
 # apidoc_module_dir = '../src/invert4geom'
 # apidoc_excluded_paths = ['tests']
 # apidoc_separate_modules = False
+autoapi_dirs = ["../src/invert4geom"]
+autoapi_type = "python"
+autoapi_add_toctree_entry = False
+autodoc_typehints = "description"
 
 # HTML output configuration
 # -----------------------------------------------------------------------------

diff --git a/docs/index.md b/docs/index.md
@@ -27,7 +27,8 @@ gallery/index.md
 user_guide/index.md
 ```
 
-<!-- ```{toctree}
+<!--
+```{toctree}
 :maxdepth: 1
 :hidden:
 :caption: 🚶 User guide
@@ -39,20 +40,23 @@ user_guide/including_starting_model
 user_guide/adhering_to_constraints
 user_guide/combining_it_all
 user_guide/estimating_regional_field
-``` -->
+```
+-->
 
-<!-- ```{toctree}
+<!--
+```{toctree}
 :maxdepth: 1
 :hidden:
 :caption: 📚 Gallery
 gallery/index.md
-``` -->
+```
+-->
 
 ```{toctree}
 :maxdepth: 2
 :hidden:
 :caption: 📖 Reference documentation
-api/invert4geom
+api.md
 citing.md
 changelog.md
 references.rst
@@ -94,7 +98,7 @@ Start a discussion on GitHub!
 :::{grid-item-card} {octicon}`file-badge` Reference documentation
 :text-align: center
 A list of modules and functions
-```{button-ref} api/invert4geom
+```{button-ref} api
     :click-parent:
     :color: primary
     :outline:

diff --git a/pyproject.toml b/pyproject.toml
@@ -74,6 +74,7 @@ docs = [
   "sphinx>=4.0",
   "myst_parser",
   "sphinx_copybutton",
+  "sphinx_autoapi",
   "sphinx_autodoc_typehints",
   "sphinx-book-theme>=0.3",
   "sphinx_design",