From ec7236bdb27fdc3c6ba71481ab94ecf97c4ca642 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Mon, 19 May 2025 12:45:44 -0700 Subject: [PATCH 1/5] enable strict mode docs in mkdocs.yml --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 7823410b1..36d13ac71 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ site_description: >- repo_name: planetlabs/planet-client-python repo_url: https://github.com/planetlabs/planet-client-python edit_uri: "" +strict: true theme: name: 'material' From dc2efe1dbcfff9388260f4fa7165caa1207b0a8f Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Mon, 19 May 2025 13:48:09 -0700 Subject: [PATCH 2/5] fix intra-doc link --- docs/cli/cli-orders.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cli/cli-orders.md b/docs/cli/cli-orders.md index 0fe3bff0a..44f9e6a34 100644 --- a/docs/cli/cli-orders.md +++ b/docs/cli/cli-orders.md @@ -635,6 +635,7 @@ To clip and composite you need to specify the clip in the tools (instead of `--c not use `--clip` and `--tools` in the same call. There is not yet CLI calls to generate the `tools.json`, so you can just use the [following json](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-clip-composite.json): + ```json [ { @@ -882,7 +883,7 @@ planet orders request \ ``` Or get the 5 latest cloud free images in an area and create an order that clips to that area, using -[geometry.geojson](data/geometry.geojson) from above: +[geometry.geojson](#geometry.geojson) from above: ```sh ids=$(planet data filter --geom geometry.geojson --range clear_percent gt 90 \ From a0632bea5d866b5a28e66b69d7ac1c06618fe6fa Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Mon, 19 May 2025 13:50:31 -0700 Subject: [PATCH 3/5] Update doc strings for strict mkdocs checking. --- planet/clients/data.py | 10 +++++----- planet/clients/subscriptions.py | 11 +++++++---- planet/http.py | 2 +- planet/order_request.py | 16 +++++++++++++++- planet/subscription_request.py | 16 +++++++++++++++- 5 files changed, 43 insertions(+), 12 deletions(-) diff --git a/planet/clients/data.py b/planet/clients/data.py index fbbe4916d..acdd90231 100644 --- a/planet/clients/data.py +++ b/planet/clients/data.py @@ -141,7 +141,7 @@ async def search( search_filter: Structured search criteria to apply. If None, no search criteria is applied. sort: Field and direction to order results by. Valid options are - given in SEARCH_SORT. + given in SEARCH_SORT. name: The name of the saved search. limit: Maximum number of results to return. When set to 0, no maximum is applied. @@ -368,7 +368,7 @@ async def run_search(self, Parameters: search_id: Stored search identifier. sort: Field and direction to order results by. Valid options are - given in SEARCH_SORT. + given in SEARCH_SORT. limit: Maximum number of results to return. When set to 0, no maximum is applied. @@ -531,7 +531,7 @@ async def get_asset(self, Raises: planet.exceptions.APIError: On API error. planet.exceptions.ClientError: If asset type identifier is not - valid. + valid. """ item_type_id = validate_data_item_type(item_type_id) assets = await self.list_item_assets(item_type_id, item_id) @@ -554,7 +554,7 @@ async def activate_asset(self, asset: dict): Raises: planet.exceptions.APIError: On API error. planet.exceptions.ClientError: If asset description is not - valid. + valid. """ try: status = asset['status'] @@ -670,7 +670,7 @@ async def download_asset(self, Raises: planet.exceptions.APIError: On API error. planet.exceptions.ClientError: If asset is not active or asset - description is not valid. + description is not valid. """ try: location = asset['location'] diff --git a/planet/clients/subscriptions.py b/planet/clients/subscriptions.py index 0638ec102..55fe07a93 100644 --- a/planet/clients/subscriptions.py +++ b/planet/clients/subscriptions.py @@ -113,7 +113,6 @@ async def list_subscriptions(self, limit (int): limit the number of subscriptions in the results. When set to 0, no maximum is applied. page_size (int): number of subscriptions to return per page. - TODO: user_id Datetime args (created, end_time, start_time, updated) can either be a date-time or an interval, open or closed. Date and time expressions adhere @@ -132,6 +131,8 @@ async def list_subscriptions(self, ClientError: on a client error. """ + # TODO from old doc string, which breaks strict document checking: + # Add Parameter user_id class _SubscriptionsPager(Paged): """Navigates pages of messages about subscriptions.""" ITEMS_KEY = 'subscriptions' @@ -209,7 +210,7 @@ async def bulk_create_subscriptions(self, requests: List[dict]) -> Dict: Args: requests (List[dict]): A list of dictionaries where each dictionary - represents a subscription to be created. + represents a subscription to be created. Raises: APIError: If the API returns an error response. @@ -368,7 +369,6 @@ async def get_results(self, filter out results with status not in this set. limit (int): limit the number of subscriptions in the results. When set to 0, no maximum is applied. - TODO: created, updated, completed, user_id Yields: dict: description of a subscription results. @@ -378,6 +378,8 @@ async def get_results(self, ClientError: on a client error. """ + # TODO from old doc string, which breaks strict document checking: + # Add Parameters created, updated, completed, user_id class _ResultsPager(Paged): """Navigates pages of messages about subscription results.""" ITEMS_KEY = 'results' @@ -415,7 +417,6 @@ async def get_results_csv( subscription_id (str): id of a subscription. status (Set[str]): pass result with status in this set, filter out results with status not in this set. - TODO: created, updated, completed, user_id Yields: str: a row from a CSV file. @@ -424,6 +425,8 @@ async def get_results_csv( APIError: on an API server error. ClientError: on a client error. """ + # TODO from old doc string, which breaks strict document checking: + # Add Parameters created, updated, completed, user_id url = f'{self._base_url}/{subscription_id}/results' params = {'status': [val for val in status or {}], 'format': 'csv'} diff --git a/planet/http.py b/planet/http.py index b09392369..d43e2e389 100644 --- a/planet/http.py +++ b/planet/http.py @@ -456,7 +456,7 @@ def client(self, A client instance. Raises: - ClientError when no such client can be had. + planet.exceptions.ClientError: when no such client can be had. """ # To avoid circular dependency. diff --git a/planet/order_request.py b/planet/order_request.py index e562f3012..31a600c8d 100644 --- a/planet/order_request.py +++ b/planet/order_request.py @@ -620,7 +620,21 @@ def band_math_tool(b1: str, in these files. Parameters: - b1-b15: An expression defining how the output band should be computed. + b1: An expression defining how the output band should be computed. + b2: An expression defining how the output band should be computed. + b3: An expression defining how the output band should be computed. + b4: An expression defining how the output band should be computed. + b5: An expression defining how the output band should be computed. + b6: An expression defining how the output band should be computed. + b7: An expression defining how the output band should be computed. + b8: An expression defining how the output band should be computed. + b9: An expression defining how the output band should be computed. + b10: An expression defining how the output band should be computed. + b11: An expression defining how the output band should be computed. + b12: An expression defining how the output band should be computed. + b13: An expression defining how the output band should be computed. + b14: An expression defining how the output band should be computed. + b15: An expression defining how the output band should be computed. pixel_type: A value indicating what the output pixel type should be. Raises: diff --git a/planet/subscription_request.py b/planet/subscription_request.py index 8fb52a00d..2380c3c85 100644 --- a/planet/subscription_request.py +++ b/planet/subscription_request.py @@ -613,7 +613,21 @@ def band_math_tool(b1: str, in these files. Parameters: - b1-b15: An expression defining how the output band should be computed. + b1: An expression defining how the output band should be computed. + b2: An expression defining how the output band should be computed. + b3: An expression defining how the output band should be computed. + b4: An expression defining how the output band should be computed. + b5: An expression defining how the output band should be computed. + b6: An expression defining how the output band should be computed. + b7: An expression defining how the output band should be computed. + b8: An expression defining how the output band should be computed. + b9: An expression defining how the output band should be computed. + b10: An expression defining how the output band should be computed. + b11: An expression defining how the output band should be computed. + b12: An expression defining how the output band should be computed. + b13: An expression defining how the output band should be computed. + b14: An expression defining how the output band should be computed. + b15: An expression defining how the output band should be computed. pixel_type: A value indicating what the output pixel type should be. Raises: From 169e133873b8b2d80ad75c3409a9c72c89a22c48 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Mon, 19 May 2025 14:09:43 -0700 Subject: [PATCH 4/5] Fix mangled links. --- docs/cli/cli-data.md | 4 ++-- docs/cli/cli-orders.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cli/cli-data.md b/docs/cli/cli-data.md index dda316706..ce779a120 100644 --- a/docs/cli/cli-data.md +++ b/docs/cli/cli-data.md @@ -41,7 +41,7 @@ command will do the same thing as the previous one: planet data search PSScene --filter filter.json | jq > recent-psscene.json ``` -You can read a bit [more about jq]((cli-intro.md#jq) in the CLI intro. +You can read a bit [more about jq](cli-intro.md#jq) in the CLI intro. ### Output to stdin @@ -412,7 +412,7 @@ Will result in output like: You can see how the yearly output of Planet has gone up, though it actually went down in 2022 as the upgrade to SuperDove meant much larger swaths, so the number of individual items went down even as we captured the whole earth. The API does not support an 'all time' interval to get the total of all collections for an area, but -you can easily use [jq]((cli-intro.md#jq) to total up the results of an interval count: +you can easily use [jq](cli-intro.md#jq) to total up the results of an interval count: ```sh curl -s https://raw.githubusercontent.com/ropensci/geojsonio/main/inst/examples/california.geojson \ diff --git a/docs/cli/cli-orders.md b/docs/cli/cli-orders.md index 44f9e6a34..e1b36d5fa 100644 --- a/docs/cli/cli-orders.md +++ b/docs/cli/cli-orders.md @@ -42,7 +42,7 @@ The `--pretty` flag is built into most Planet CLI commands, and it formats the J more readable. You can also use `jq`, a powerful command-line JSON-processing tool, that is mentioned in -the [CLI introduction]((cli-intro.md#jq). +the [CLI introduction](cli-intro.md#jq). ```sh planet orders list | jq From f407424e856c3e595f3a0dea5979e68b8ae94e62 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Mon, 19 May 2025 14:17:44 -0700 Subject: [PATCH 5/5] doc tests need pytest and tooling. Add to noxfile. --- noxfile.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index 620014b82..833c1c3c5 100644 --- a/noxfile.py +++ b/noxfile.py @@ -68,7 +68,7 @@ def lint(session): @nox.session def docs_test(session): - session.install("-e", ".[docs]") + session.install("-e", ".[docs, test]") options = session.posargs @@ -88,6 +88,7 @@ def docs_test(session): @nox.session def docs(session): + """Build documentation locally""" session.install("-e", ".[docs]") session.run("mkdocs", "build")