switch docs from autoapi to autodoc

Author: mdtanker

.readthedocs.yaml

@@ -7,17 +7,13 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3.12"
-  jobs:
-    create_environment:
-      - asdf plugin add uv
-      - asdf install uv latest
-      - asdf global uv latest
-      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --only-group
-        docs
-      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv pip install .
-        --no-deps
-    install:
-      - "true"
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --group docs
+    - uv run python -m sphinx -T -b html -d docs/_build/doctrees -D language=en
+      docs $READTHEDOCS_OUTPUT/html
 
 sphinx:
   configuration: docs/conf.py

docs/api/polartoolkit.rst

@@ -0,0 +1,50 @@
+polartoolkit package
+====================
+
+.. automodule:: polartoolkit
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Submodules
+----------
+
+polartoolkit.fetch module
+-------------------------
+
+.. automodule:: polartoolkit.fetch
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+polartoolkit.maps module
+------------------------
+
+.. automodule:: polartoolkit.maps
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+polartoolkit.profiles module
+----------------------------
+
+.. automodule:: polartoolkit.profiles
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+polartoolkit.regions module
+---------------------------
+
+.. automodule:: polartoolkit.regions
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+polartoolkit.utils module
+-------------------------
+
+.. automodule:: polartoolkit.utils
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/conf.py

@@ -1,22 +1,24 @@
-import polartoolkit
+import importlib.metadata
 
 project = "polartoolkit"
 copyright = "2023, Matt Tankersley"
 author = "Matt Tankersley"
-version = release = polartoolkit.__version__
+version = release = importlib.metadata.version("polartoolkit")
+
 extensions = [
-    "sphinx.ext.autodoc",  # needed for typehints
-    "sphinx.ext.viewcode",
+    "myst_parser",
+    "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.napoleon",
-    "autoapi.extension",
     "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
     "sphinx_copybutton",
-    "myst_parser",
-    "sphinx_design",
+    "sphinx.ext.viewcode",
     "nbsphinx",
     "sphinxcontrib.bibtex",
+    "sphinx_design",
 ]
+
 source_suffix = [".rst", ".md"]
 exclude_patterns = [
     "_build",
@@ -29,8 +31,6 @@
 
 bibtex_bibfiles = ["_polartoolkit_refs.bib"]
 
-nbsphinx_execute = "never"
-
 myst_enable_extensions = [
     "colon_fence",
 ]
@@ -47,11 +47,11 @@
     "rioxarray": ("https://corteva.github.io/rioxarray/stable/", None),
     "xrft": ("https://xrft.readthedocs.io/en/stable/", None),
     "harmonica": ("https://www.fatiando.org/harmonica/latest/", None),
-    "numba": ("https://numba.pydata.org/numba-doc/latest/", None),
+    "numba": ("https://numba.readthedocs.io/en/stable/index.html", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "pyvista": ("https://docs.pyvista.org/", None),
     "pooch": ("https://www.fatiando.org/pooch/latest/", None),
-    "cartopy": ("https://scitools.org.uk/cartopy/docs/latest/", None),
+    "cartopy": ("https://cartopy.readthedocs.io/latest/", None),
     # "tqdm": ("https://tqdm.github.io/", None),
     "pygmt": ("https://www.pygmt.org/latest/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
@@ -76,13 +76,15 @@
 add_module_names = False
 add_function_parentheses = False
 
-# API doc configuration
-# -----------------------------------------------------------------------------
-autoapi_dirs = ["../src/polartoolkit"]
-autoapi_type = "python"
-autoapi_add_toctree_entry = False
-autodoc_typehints = "description"
 
+nbsphinx_execute = "never"
+
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'png2x'}",
+    "--InlineBackend.rc=figure.dpi=96",
+]
+
+nbsphinx_kernel_name = "python3"
 
 # HTML output configuration
 # -----------------------------------------------------------------------------

docs/index.md

@@ -76,17 +76,17 @@ datasets/greenland_arctic/index.md
 ```{toctree}
 :maxdepth: 2
 :hidden:
-:caption: 📖 Reference documentation
-autoapi/polartoolkit/index
-changelog.md
-references.rst
+:caption: 📖 API
+api/polartoolkit
 ```
 
 ```{toctree}
 :maxdepth: 1
 :hidden:
 :caption: ℹ️ Other resources
 contributing.md
+changelog.md
+references.rst
 Source code on GitHub <https://github.com/mdtanker/polartoolkit>
 ```
 
@@ -118,7 +118,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} autoapi/polartoolkit/index
+```{button-ref} api/polartoolkit
     :click-parent:
     :color: primary
     :outline:

environment.yml

@@ -20,9 +20,9 @@ dependencies:
   - deprecation
   - openpyxl
   - pyproj
-  - geopandas>=1.0 
+  - geopandas>=1.0
   - pyogrio
-  - zarr>=3.0 
+  - zarr>=3.0
   - python-dotenv
   - requests
   - earthaccess
@@ -47,7 +47,6 @@ dependencies:
   - ipykernel
   - nbconvert
   - sphinxcontrib-bibtex
-  - sphinx-autoapi
   - sphinx-design
   # dev
   - jupyterlab

noxfile.py

@@ -18,11 +18,7 @@ def lint(session: nox.Session) -> None:
     """
     session.install("pre-commit")
     session.run(
-        "pre-commit",
-        "run",
-        "--all-files",
-        "--show-diff-on-failure",
-        *session.posargs,
+        "pre-commit", "run", "--all-files", "--show-diff-on-failure", *session.posargs
     )
 
 
@@ -66,8 +62,7 @@ def tests(session: nox.Session) -> None:
 @nox.session(reuse_venv=True, default=False)
 def docs(session: nox.Session) -> None:
     """
-    Build the docs. Pass --non-interactive to avoid serving. First positional
-    argument is the target directory.
+    Build the docs. Pass --non-interactive to avoid serving. First positional argument is the target directory.
     """
 
     doc_deps = nox.project.dependency_groups(PROJECT, "docs")
@@ -96,6 +91,24 @@ def docs(session: nox.Session) -> None:
         session.run("sphinx-build", "--keep-going", *shared_args)
 
 
+@nox.session(default=False)
+def build_api_docs(session: nox.Session) -> None:
+    """
+    Build (regenerate) API docs.
+    """
+
+    session.install("sphinx")
+    session.run(
+        "sphinx-apidoc",
+        "-o",
+        "docs/api/",
+        "--module-first",
+        "--no-toc",
+        "--force",
+        "src/polartoolkit",
+    )
+
+
 @nox.session
 def build(session: nox.Session) -> None:
     """

pyproject.toml

@@ -80,7 +80,6 @@ docs = [
   "ipykernel",
   "nbconvert",
   "sphinxcontrib-bibtex",
-  "sphinx_autoapi",
   "sphinx_design",
 ]