diff --git a/.github/workflows/cicd.yaml b/.github/workflows/cicd.yaml index c77ba14a..17801732 100644 --- 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 index 90f6e574..ac0839e4 100644 --- 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 index 908694a3..1c7b79aa 100644 --- a/.gitignore +++ b/.gitignore @@ -121,9 +121,6 @@ celerybeat-schedule # skaffold temporary build/deploy files build.out -# pdocs -docs/api/* - # Direnv .envrc @@ -131,4 +128,4 @@ docs/api/* venv # IDE -.vscode \ No newline at end of file +.vscode diff --git a/Dockerfile.docs b/Dockerfile.docs index 5cb3eff3..6fa5abb3 100644 --- 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 index 9c441f18..ca990771 100644 --- 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 new file mode 100644 index 00000000..f8129a24 --- /dev/null +++ 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 new file mode 100644 index 00000000..a07cb574 --- /dev/null +++ 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 new file mode 100644 index 00000000..d0d83158 --- /dev/null +++ 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 new file mode 100644 index 00000000..fa2704f7 --- /dev/null +++ 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 new file mode 100644 index 00000000..ba456471 --- /dev/null +++ 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 new file mode 100644 index 00000000..b0c91be2 --- /dev/null +++ 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 new file mode 100644 index 00000000..353f1553 --- /dev/null +++ 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 new file mode 100644 index 00000000..e5df4c47 --- /dev/null +++ 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 new file mode 100644 index 00000000..f7cb1ea8 --- /dev/null +++ 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 new file mode 100644 index 00000000..b484df41 --- /dev/null +++ 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 new file mode 100644 index 00000000..f7b78c14 --- /dev/null +++ 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 new file mode 100644 index 00000000..3569f436 --- /dev/null +++ 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 new file mode 100644 index 00000000..2712843c --- /dev/null +++ b/docs/api/stac_fastapi/pgstac/version.md @@ -0,0 +1 @@ +::: stac_fastapi.pgstac.version diff --git a/mkdocs.yml b/mkdocs.yml index 700c5241..215c838f 100644 --- 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 index 8dbc6879..2183a6f5 100644 --- 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 index cbc4676a..fbad1f58 100644 --- 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 index 813923ac..582b4552 100644 --- 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.