Fix docs deps for RTD and docstrings warnings

.readthedocs.yml

@@ -14,7 +14,7 @@ build:
 
 mkdocs:
   configuration: "mkdocs.yml"
-  fail_on_warning: false
+  fail_on_warning: true
 
 # Use our docs/requirements.txt during installation.
 python:

docs/requirements.txt

@@ -1,9 +1,10 @@
 mkdocs==1.6.0
 # Material for MkDocs theme
-mkdocs-material==9.5.19
+mkdocs-material==9.5.32
 # Render custom markdown for version added/changed/remove notes
 mkdocs-version-annotations==1.0.0
 # Automatic documentation from sources, for MkDocs
-mkdocstrings==0.24.3
-mkdocstrings-python==1.10.0
+griffe==1.1.1
+mkdocstrings-python==1.10.8
+mkdocstrings==0.25.2
 markdown-data-tables==1.0.0

pynautobot/core/api.py

@@ -126,7 +126,7 @@ def version(self):
         if specific features or syntaxes are available.
 
         Returns:
-            str: The Nautobot API version string.
+            (str): The Nautobot API version string.
 
         Raises:
             requests.exceptions.RequestException: If there is an error fetching the
@@ -158,7 +158,7 @@ def openapi(self):
         This can be useful for tools like code generation or API clients in other languages.
 
         Returns:
-            dict: The OpenAPI specification document as a Python dictionary.
+            (dict): The OpenAPI specification document as a Python dictionary.
 
         Raises:
             requests.exceptions.RequestException: If there is an error fetching the
@@ -196,7 +196,7 @@ def status(self):
         **Availability:** Requires Nautobot version 2.10.0 or newer.
 
         Returns:
-            dict: A dictionary containing the status information as returned by Nautobot.
+            (dict): A dictionary containing the status information as returned by Nautobot.
 
         Raises:
             pynautobot.exceptions.RequestError: If the request to Nautobot fails.

pynautobot/core/app.py

@@ -29,7 +29,7 @@ class App(object):
     Calls to attributes are returned as Endpoint objects.
 
     Returns:
-        Endpoint: Matching requested attribute.
+        (Endpoint): Matching requested attribute.
 
     Raises:
         RequestError: If requested endpoint doesn't exist.
@@ -77,7 +77,7 @@ def choices(self):
         """Returns _choices response from App.
 
         Returns:
-            Raw response from Nautobot's _choices endpoint.
+            (List[Response]): Raw response from Nautobot's _choices endpoint.
         """
         if self._choices:
             return self._choices
@@ -94,7 +94,7 @@ def get_custom_fields(self):
         """Returns custom-fields response from app.
 
         Returns:
-            Raw response from Nautobot's custom-fields endpoint.
+            (List[Response]): Raw response from Nautobot's custom-fields endpoint.
 
         Raises:
             RequestError: If called for an invalid endpoint.
@@ -135,7 +135,7 @@ def get_custom_field_choices(self):
         """Returns custom-field-choices response from app.
 
         Returns:
-            Raw response from Nautobot's custom-field-choices endpoint.
+            (List[Response]): Raw response from Nautobot's custom-field-choices endpoint.
 
         Raises:
             RequestError: If called for an invalid endpoint.
@@ -170,7 +170,7 @@ def config(self):
         """Returns config response from app.
 
         Returns:
-            dict: Raw response from Nautobot's config endpoint.
+            (dict): Raw response from Nautobot's config endpoint.
 
         Raises:
             RequestError: If called for an invalid endpoint.
@@ -215,7 +215,7 @@ class PluginsApp(object):
     but you need to add "plugins" to the request URL path.
 
     Returns:
-        App: With "plugins" added to the path.
+        (App): With "plugins" added to the path.
     """
 
     def __init__(self, api):
@@ -234,7 +234,7 @@ def installed_plugins(self):
         """Returns raw response with installed plugins.
 
         Returns:
-            Raw response from Nautobot's installed plugins.
+            (List[Response]): Raw response from Nautobot's installed plugins.
 
         Examples:
             >>> nb.plugins.installed_plugins()

pynautobot/core/endpoint.py

@@ -72,7 +72,7 @@ def _lookup_ret_obj(self, name, model):
             model (obj): The application model that contains unique Record objects.
 
         Returns:
-            Record: Unique response object if exists, otherwise a generic `Record` object.
+            (Record): Unique response object if exists, otherwise a generic `Record` object.
         """
         if model:
             name = name.title().replace("_", "").replace("-", "")
@@ -86,7 +86,7 @@ def all(self, *args, **kwargs):
 
         Returns all objects from an endpoint.
 
-        Args:
+        Optional Args:
             api_version (str, optional): Override default or globally-set Nautobot REST API
                 version for this single request.
             limit (int, optional): Overrides the max page size on
@@ -95,7 +95,7 @@ def all(self, *args, **kwargs):
                 will be made as you iterate through the result set.
             offset (int, optional): Overrides the offset on paginated returns.
         Returns:
-            list: List of :py:class:`.Record` objects.
+            (list): List of :py:class:`.Record` objects.
 
         Examples:
             >>> nb.dcim.devices.all()
@@ -106,15 +106,15 @@ def all(self, *args, **kwargs):
     def get(self, *args, **kwargs):
         """Queries the DetailsView of a given endpoint.
 
-        Args:
+        Optional Args:
             key (int, optional): ID for the item to be retrieved.
             **kwargs (str, optional): Accepts the same keyword args as filter().
                 Any search argument the endpoint accepts can be added as a keyword arg.
             api_version (str, optional): Override default or globally-set Nautobot REST API
                 version for this single request.
 
         Returns:
-            Union[Record, None]: A single :py:class:`.Record` object or None.
+            (Union[Record, None]): A single :py:class:`.Record` object or None.
 
         Raises:
             ValueError: If kwarg search returns more than one value.
@@ -184,7 +184,7 @@ def filter(self, *args, api_version=None, **kwargs):
                 Nautobot REST API version for this single request.
 
         Returns:
-            list: A list of :py:class:`.Record` objects.
+            (list): A list of :py:class:`.Record` objects.
 
         Examples:
             To return a list of objects matching a named argument filter.
@@ -248,7 +248,7 @@ def create(self, *args, api_version=None, **kwargs):
                 Nautobot REST API version for this single request.
 
         Returns:
-            Union[Record, List[Record]]: A list or single :py:class:`.Record` object depending
+            (Union[Record, List[Record]]): A list or single :py:class:`.Record` object depending
                 on whether a bulk creation was requested.
 
         Examples:
@@ -303,11 +303,11 @@ def update(self, *args, **kwargs):
             **kwargs (str, optional): See Below.
 
         Keyword Arguments:
-            * *id* (``string``) -- Identifier of the object being updated.
-            * *data* (``dict``) -- Key/value pairs to update the record object with.
+            id (string): Identifier of the object being updated.
+            data (dict): Key/value pairs to update the record object with.
 
         Returns:
-            Union[Record, List[Record]]: A list or single :py:class:`.Record` object depending
+            (Union[Record, List[Record]]): A list or single :py:class:`.Record` object depending
                 on whether a bulk update was requested.
 
         Examples:
@@ -409,7 +409,7 @@ def delete(self, objects):
             objects (list): A list of either IDs or Records to delete.
 
         Returns:
-            bool: True if bulk DELETE operation was successful.
+            (bool): True if bulk DELETE operation was successful.
 
         Examples:
             Deleting all `devices`:
@@ -469,7 +469,7 @@ def choices(self, api_version=None):
                 Nautobot REST API version for this single request.
 
         Returns:
-            dict: Dict containing the available choices.
+            (dict): Dict containing the available choices.
 
         Example (from Nautobot 2.8.x):
             >>> from pprint import pprint
@@ -527,7 +527,7 @@ def count(self, *args, api_version=None, **kwargs):
                 Nautobot REST API version for this single request.
 
         Returns:
-            int: Integer with count of objects returned by query.
+            (int): Integer with count of objects returned by query.
 
         Examples:
             To return a count of objects matching a named argument filter.
@@ -579,11 +579,11 @@ def list(self, api_version=None, **kwargs):
 
         Args:
             api_version (str, optional): Override default or globally set Nautobot REST API version for this single request.
-            **kwargs: Key/value pairs that get converted into URL parameters when passed to the endpoint.
+            **kwargs (dict): Key/value pairs that get converted into URL parameters when passed to the endpoint.
                 E.g. ``.list(method='get_facts')`` would be converted to ``.../?method=get_facts``.
 
         Returns:
-            Union[Dict, List[Dict]]: A dictionary or list of dictionaries retrieved from Nautobot.
+            (Union[Dict, List[Dict]]): A dictionary or list of dictionaries retrieved from Nautobot.
         """
 
         api_version = api_version or self.parent_obj.api.api_version
@@ -608,7 +608,7 @@ def create(self, data=None, api_version=None):
                 Nautobot REST API version for this single request.
 
         Returns:
-            Union[Dict, List[Dict]]: A dictionary or list of dictionaries representing
+            (Union[Dict, List[Dict]]): A dictionary or list of dictionaries representing
                 the items created in Nautobot.
         """
         data = data or {}
@@ -642,7 +642,7 @@ def run(self, *args, api_version=None, **kwargs):
                 Nautobot REST API version for this single request.
 
         Returns:
-            obj: Job details: job_result object uuid found at `obj.result.id`.
+            obj (str): Job details: job_result object uuid found at `obj.result.id`.
 
         Examples:
             To run a job for verifying hostnames:
@@ -693,7 +693,7 @@ def run(self, query_id, *args, **kwargs):
                 that is being ran.
 
         Returns:
-            An API response from the execution of the saved graphql query.
+            (Response): An API response from the execution of the saved graphql query.
 
         Examples:
             To run a query no variables: