switch to mkdocstring (#223)

vincentsarago · web-flow · commit d0409131a244 · 2025-04-04T14:14:53.000+02:00
diff --git a/.github/workflows/cicd.yaml b/.github/workflows/cicd.yaml
@@ -119,8 +119,5 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install .[docs,dev,server]
 
-      - name: Generate API docs
-        run: make docs
-
       - name: Build documentation
         run: mkdocs build --strict
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -35,21 +35,6 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install -e .[docs]
-      - name: Update API docs
-        run: |
-          pdocs as_markdown \
-            --output_dir docs/api/ \
-            --exclude_source \
-            --overwrite \
-            stac_fastapi.pgstac
-        env:
-          POSTGRES_USER: username
-          POSTGRES_PASS: password
-          POSTGRES_DBNAME: postgis
-          POSTGRES_HOST: localhost
-          POSTGRES_PORT: 5432
-          POSTGRES_HOST_READER: localhost
-          POSTGRES_HOST_WRITER: localhost
       - name: Build docs
         run: mkdocs build --site-dir site
       - name: Upload artifact
diff --git a/.gitignore b/.gitignore
@@ -121,14 +121,11 @@ celerybeat-schedule
 # skaffold temporary build/deploy files
 build.out
 
-# pdocs
-docs/api/*
-
 # Direnv
 .envrc
 
 # Virtualenv
 venv
 
 # IDE
-.vscode
+.vscode
diff --git a/Dockerfile.docs b/Dockerfile.docs
@@ -4,18 +4,11 @@ FROM python:3.10-slim
 RUN apt update && apt install -y build-essential
 
 RUN python -m pip install --upgrade pip
-RUN python -m pip install mkdocs mkdocs-material pdocs
 
 COPY . /opt/src
 
 WORKDIR /opt/src
 
-RUN python -m pip install .
+RUN python -m pip install ".[docs]"
 
-CMD ["pdocs", \
-    "as_markdown", \
-    "--output_dir", \
-    "docs/api/", \
-    "--exclude_source", \
-    "--overwrite", \
-    "stac_fastapi.pgstac"]
+CMD ["mkdocs", "build"]
diff --git a/docker-compose.docs.yml b/docker-compose.docs.yml
@@ -7,12 +7,5 @@ services:
       context: .
       dockerfile: Dockerfile.docs
     platform: linux/amd64
-    environment:
-      - POSTGRES_USER=username
-      - POSTGRES_PASS=password
-      - POSTGRES_DBNAME=postgis
-      - POSTGRES_HOST_READER=database
-      - POSTGRES_HOST_WRITER=database
-      - POSTGRES_PORT=5432
     volumes:
       - .:/opt/src
diff --git a/docs/api/stac_fastapi/pgstac/app.md b/docs/api/stac_fastapi/pgstac/app.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.app
diff --git a/docs/api/stac_fastapi/pgstac/config.md b/docs/api/stac_fastapi/pgstac/config.md
@@ -0,0 +1,3 @@
+::: stac_fastapi.pgstac.config
+    options:
+      show_source: true
diff --git a/docs/api/stac_fastapi/pgstac/core.md b/docs/api/stac_fastapi/pgstac/core.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.core
diff --git a/docs/api/stac_fastapi/pgstac/db.md b/docs/api/stac_fastapi/pgstac/db.md
@@ -0,0 +1,3 @@
+::: stac_fastapi.pgstac.db
+    options:
+      show_source: true
diff --git a/docs/api/stac_fastapi/pgstac/extensions/filter.md b/docs/api/stac_fastapi/pgstac/extensions/filter.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.extensions.filter
diff --git a/docs/api/stac_fastapi/pgstac/extensions/index.md b/docs/api/stac_fastapi/pgstac/extensions/index.md
@@ -0,0 +1,8 @@
+# Module stac_fastapi.pgstac.extensions
+
+pgstac extension customisations.
+
+## Sub-modules
+
+* [stac_fastapi.pgstac.extensions.filter](filter.md)
+* [stac_fastapi.pgstac.extensions.query](query.md)
diff --git a/docs/api/stac_fastapi/pgstac/extensions/query.md b/docs/api/stac_fastapi/pgstac/extensions/query.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.extensions.query
diff --git a/docs/api/stac_fastapi/pgstac/index.md b/docs/api/stac_fastapi/pgstac/index.md
@@ -0,0 +1,14 @@
+# Module stac_fastapi.pgstac
+
+stac_fastapi.pgstac module.
+
+## Sub-modules
+
+* [stac_fastapi.pgstac.app](app.md)
+* [stac_fastapi.pgstac.config](config.md)
+* [stac_fastapi.pgstac.core](core.md)
+* [stac_fastapi.pgstac.db](db.md)
+* [stac_fastapi.pgstac.extensions](extensions/index.md)
+* [stac_fastapi.pgstac.models](models/index.md)
+* [stac_fastapi.pgstac.transactions](transactions.md)
+* [stac_fastapi.pgstac.utils](utils.md)
diff --git a/docs/api/stac_fastapi/pgstac/models/index.md b/docs/api/stac_fastapi/pgstac/models/index.md
@@ -0,0 +1,7 @@
+# Module stac_fastapi.pgstac.models
+
+stac_fastapi.pgstac.models module.
+
+## Sub-modules
+
+* [stac_fastapi.pgstac.models.links](links.md)
diff --git a/docs/api/stac_fastapi/pgstac/models/links.md b/docs/api/stac_fastapi/pgstac/models/links.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.models.links
diff --git a/docs/api/stac_fastapi/pgstac/transactions.md b/docs/api/stac_fastapi/pgstac/transactions.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.transactions
diff --git a/docs/api/stac_fastapi/pgstac/utils.md b/docs/api/stac_fastapi/pgstac/utils.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.utils
diff --git a/docs/api/stac_fastapi/pgstac/version.md b/docs/api/stac_fastapi/pgstac/version.md
@@ -0,0 +1 @@
+::: stac_fastapi.pgstac.version
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -17,26 +17,49 @@ nav:
   - Home: "index.md"
   - API:
       - stac_fastapi.pgstac:
-          - index: api/stac_fastapi/pgstac/index.md
+          - module: api/stac_fastapi/pgstac/index.md
           - app: api/stac_fastapi/pgstac/app.md
           - config: api/stac_fastapi/pgstac/config.md
           - core: api/stac_fastapi/pgstac/core.md
           - db: api/stac_fastapi/pgstac/db.md
           - extensions:
-              - index: api/stac_fastapi/pgstac/extensions/index.md
+              - module: api/stac_fastapi/pgstac/extensions/index.md
               - filter: api/stac_fastapi/pgstac/extensions/filter.md
               - query: api/stac_fastapi/pgstac/extensions/query.md
           - models:
-              - index: api/stac_fastapi/pgstac/models/index.md
+              - module: api/stac_fastapi/pgstac/models/index.md
               - links: api/stac_fastapi/pgstac/models/links.md
           - transactions: api/stac_fastapi/pgstac/transactions.md
           - utils: api/stac_fastapi/pgstac/utils.md
-          - version: api/stac_fastapi/pgstac/version.md
   - Development - Contributing: "contributing.md"
   - Release Notes: "release-notes.md"
 
 plugins:
   - search
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          options:
+            docstring_section_style: list
+            docstring_style: google
+            line_length: 100
+            separate_signature: true
+            show_root_heading: true
+            show_signature_annotations: true
+            show_source: false
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            extensions:
+              - griffe_inherited_docstrings
+          inventories:
+            - https://docs.python.org/3/objects.inv
+            - https://docs.pydantic.dev/latest/objects.inv
+            - https://fastapi.tiangolo.com/objects.inv
+            - https://www.starlette.io/objects.inv
+            - https://magicstack.github.io/asyncpg/current/objects.inv
+            - https://stac-utils.github.io/stac-fastapi/objects.inv
+            - https://www.attrs.org/en/stable/objects.inv
 
 # Theme
 theme:
diff --git a/setup.py b/setup.py
@@ -35,7 +35,14 @@
         "twine",
         "wheel",
     ],
-    "docs": ["mkdocs", "mkdocs-material", "pdocs"],
+    "docs": [
+        "black>=23.10.1",
+        "mkdocs>=1.4.3",
+        "mkdocs-jupyter>=0.24.5",
+        "mkdocs-material[imaging]>=9.5",
+        "griffe-inherited-docstrings>=1.0.0",
+        "mkdocstrings[python]>=0.25.1",
+    ],
     "server": ["uvicorn[standard]==0.34.0"],
     "awslambda": ["mangum"],
 }
diff --git a/stac_fastapi/pgstac/config.py b/stac_fastapi/pgstac/config.py
@@ -35,7 +35,12 @@
 
 
 class ServerSettings(BaseModel):
-    """Server runtime parameters."""
+    """Server runtime parameters.
+
+    Attributes:
+        search_path: Postgres search path. Defaults to "pgstac,public".
+        application_name: PgSTAC Application name. Defaults to 'pgstac'.
+    """
 
     search_path: str = "pgstac,public"
     application_name: str = "pgstac"
@@ -90,6 +95,8 @@ def testing_connection_string(self):
 
 
 class Settings(ApiSettings):
+    """Api Settings."""
+
     use_api_hydrate: bool = False
     invalid_id_chars: List[str] = DEFAULT_INVALID_ID_CHARS
     base_item_cache: Type[BaseItemCache] = DefaultBaseItemCache
diff --git a/stac_fastapi/pgstac/core.py b/stac_fastapi/pgstac/core.py
@@ -208,7 +208,7 @@ async def _get_base_item(
         """Get the base item of a collection for use in rehydrating full item collection properties.
 
         Args:
-            collection: ID of the collection.
+            collection_id: ID of the collection.
 
         Returns:
             Item.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+::: stac_fastapi.pgstac.config`
	`2`	`+ options:`
	`3`	`+ show_source: true`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+::: stac_fastapi.pgstac.db`
	`2`	`+ options:`
	`3`	`+ show_source: true`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+::: stac_fastapi.pgstac.extensions.filter`