mkdocs strict mode checks. (#1139)

* enable strict mode docs in mkdocs.yml

* fix intra-doc link

* Update doc strings for strict mkdocs checking.

* Fix mangled links.

* doc tests need pytest and tooling.  Add to noxfile.

Author: carl-adams-planet

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 \

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
@@ -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):
 
+<a name="geometry.geojson"></a>
 ```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 \

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'

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")

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']

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'}
 

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.

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:

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: