switch to mkdocstrings for API docs (#952)

Author: vincentsarago

.github/workflows/deploy_mkdocs.yml

@@ -30,35 +30,8 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install src/titiler/core src/titiler/extensions["cogeo,stac"] src/titiler/mosaic src/titiler/application
-          python -m pip install nbconvert mkdocs mkdocs-material mkdocs-jupyter pygments pdocs
+          python -m pip install -r requirements/requirement-docs.txt
 
-      - name: update API docs
-        run: |
-          pdocs as_markdown \
-            --output_dir docs/src/api \
-            --exclude_source \
-            --overwrite \
-            titiler.core.dependencies \
-            titiler.core.factory \
-            titiler.core.routing \
-            titiler.core.errors \
-            titiler.core.resources.enums \
-            titiler.core.middleware
-
-          pdocs as_markdown \
-            --output_dir docs/src/api \
-            --exclude_source \
-            --overwrite \
-            titiler.extensions.cogeo \
-            titiler.extensions.viewer \
-            titiler.extensions.stac
-
-          pdocs as_markdown \
-            --output_dir docs/src/api \
-            --exclude_source \
-            --overwrite \
-            titiler.mosaic.factory \
-            titiler.mosaic.errors
 
       - name: Deploy docs
         run: mkdocs gh-deploy --force -f docs/mkdocs.yml

.gitignore

@@ -107,4 +107,4 @@ ENV/
 
 cdk.out/
 deployment/k8s/titiler/values-test.yaml
-docs/src/api/
+

CONTRIBUTING.md

@@ -47,7 +47,7 @@ python -m pytest src/titiler/application --cov=titiler.application --cov-report=
 ```bash
 git clone https://github.com/developmentseed/titiler.git
 cd titiler
-python -m pip install nbconvert mkdocs mkdocs-material mkdocs-jupyter pygments pdocs
+python -m pip install -r requirements/requirement-docs.txt
 ```
 
 Hot-reloading docs:
@@ -62,33 +62,3 @@ Actions deploys automatically for new commits.):
 ```bash
 mkdocs gh-deploy -f docs/mkdocs.yml
 ```
-
-```bash
-pdocs as_markdown \
-   --output_dir docs/src/api \
-   --exclude_source \
-   --overwrite \
-   titiler.core.dependencies \
-   titiler.core.factory \
-   titiler.core.utils \
-   titiler.core.routing \
-   titiler.core.errors \
-   titiler.core.resources.enums \
-   titiler.core.middleware
-
-pdocs as_markdown \
-   --output_dir docs/src/api \
-   --exclude_source \
-   --overwrite \
-   titiler.extensions.cogeo \
-   titiler.extensions.viewer \
-   titiler.extensions.stac
-
-pdocs as_markdown \
-   --output_dir docs/src/api \
-   --exclude_source \
-   --overwrite \
-   titiler.mosaic.factory \
-   titiler.mosaic.resources.enums \
-   titiler.mosaic.errors
-```

docs/mkdocs.yml

@@ -92,15 +92,23 @@ nav:
       - factory: api/titiler/core/factory.md
       - routing: api/titiler/core/routing.md
       - errors: api/titiler/core/errors.md
-      - enums: api/titiler/core/resources/enums.md
       - middleware: api/titiler/core/middleware.md
+      - resources:
+        - enums: api/titiler/core/resources/enums.md
+        - responses: api/titiler/core/resources/responses.md
+      - models:
+        - OGC: api/titiler/core/models/OGC.md
+        - Mapbox/MapLibre: api/titiler/core/models/mapbox.md
+        - responses: api/titiler/core/models/responses.md
     - titiler.extensions:
       - cogeo: api/titiler/extensions/cogeo.md
       - stac: api/titiler/extensions/stac.md
       - viewer: api/titiler/extensions/viewer.md
     - titiler.mosaic:
       - factory: api/titiler/mosaic/factory.md
       - errors: api/titiler/mosaic/errors.md
+      - models:
+        - responses: api/titiler/mosaic/models/responses.md
 
   - Deployment:
     - Amazon Web Services:
@@ -118,8 +126,36 @@ nav:
 
 plugins:
   - search
+  - social
   - mkdocs-jupyter:
-      include_source: True
+      include_source: true
+      ignore: ["**/.ipynb_checkpoints/*.ipynb"]
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          paths: [src]
+          options:
+            filters:
+            - "!^__post_init__"
+            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
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://numpy.org/doc/stable/objects.inv
+            - https://rasterio.readthedocs.io/en/stable/objects.inv
+            - https://docs.pydantic.dev/latest/objects.inv
+            - https://fastapi.tiangolo.com/objects.inv
+            - https://cogeotiff.github.io/rio-tiler/objects.inv
 
 theme:
   name: material
@@ -129,6 +165,15 @@ theme:
   custom_dir: 'src/overrides'
   favicon: img/favicon.png
 
+  features:
+    - content.code.annotate
+    - content.code.copy
+    - navigation.indexes
+    - navigation.instant
+    - navigation.tracking
+    - search.suggest
+    - search.share
+
 # https://github.com/kylebarron/cogeo-mosaic/blob/mkdocs/mkdocs.yml#L50-L75
 markdown_extensions:
   - admonition
@@ -142,7 +187,9 @@ markdown_extensions:
   - pymdownx.caret:
       insert: false
   - pymdownx.details
-  - pymdownx.emoji
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.escapeall:
       hardbreak: true
       nbsp: true