Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix docs build for RTD and docstrings warnings #241

Merged
merged 1 commit into from
Oct 16, 2024
Merged

Fix docs build for RTD and docstrings warnings #241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .readthedocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
7 changes: 4 additions & 3 deletions docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
33 changes: 17 additions & 16 deletions poetry.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions pynautobot/core/api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
14 changes: 7 additions & 7 deletions pynautobot/core/app.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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):
Expand All @@ -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()
Expand Down
36 changes: 18 additions & 18 deletions pynautobot/core/endpoint.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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("-", "")
Expand All @@ -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
Expand All @@ -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()
Expand 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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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`:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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 {}
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
Loading
Loading