Skip to content

Commit

Permalink
Fixes up some docstrings.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Daverball
Daverball committed Sep 4, 2024
1 parent a029e52 commit 444d7f6
Show file tree
Hide file tree
Showing 4 changed files with 1,898 additions and 1,846 deletions.
7 changes: 4 additions & 3 deletions scripts/generate_module_hints.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,7 @@ def replace(match: re.Match[str]) -> str:

if mode == 'M':
# module -> method link
value = value.rsplit('.', 1)[-1]
value = value.replace(' ', '\u00a0')
return f':meth:`{value}`'
elif mode == 'P':
Expand All @@ -231,7 +232,7 @@ def replace(match: re.Match[str]) -> str:
value = value[:type_idx]

value = value.replace(' ', '\u00a0')
return f'`{value}`'
return f'``{value}``'
# be generous about accepting either as either
elif mode in 'UL':
if ',' in value:
Expand Down Expand Up @@ -259,15 +260,15 @@ def replace(match: re.Match[str]) -> str:
# sphinx reference
name, _ = value.split(',')
name = name.replace(' ', '\u00a0')
return f'`{name}`'
return f'``{name}``'
elif mode in ('O', 'C', 'V', 'RV', 'E'):
if isinstance(value, str):
# NOTE: Values are already escaped, so we need to unescape
# so we don't double escape.
# We also replace spaces with non-breaking spaces
# so our line-splitter can't split there.
value = value.replace('\\\\', '\\').replace(' ', '\u00a0')
return f'`{value}`'
return f'``{value}``'
else:
raise ValueError(f'Unknown reference mode {mode}')

Expand Down
93 changes: 47 additions & 46 deletions src/suitable/_module_types.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -257,15 +257,15 @@ def ansible_job_id(self, server: str | None = None) -> str:

def finished(self, server: str | None = None) -> int:
"""
Whether the asynchronous job has finished (`1`) or not (`0`).
Whether the asynchronous job has finished (``1``) or not (``0``).
Returned when: always
"""
return self.acquire(server, 'finished')

def started(self, server: str | None = None) -> int:
"""
Whether the asynchronous job has started (`1`) or not (`0`).
Whether the asynchronous job has started (``1``) or not (``0``).
Returned when: always
"""
Expand Down Expand Up @@ -780,17 +780,17 @@ class FileResults(RunnerResults):

def dest(self, server: str | None = None) -> str:
"""
Destination file/path, equal to the value passed to `path`.
Destination file/path, equal to the value passed to ``path``.
Returned when: `state=touch`, `state=hard`, `state=link`
Returned when: ``state=touch``, ``state=hard``, ``state=link``
"""
return self.acquire(server, 'dest')

def path(self, server: str | None = None) -> str:
"""
Destination file/path, equal to the value passed to `path`.
Destination file/path, equal to the value passed to ``path``.
Returned when: `state=absent`, `state=directory`, `state=file`
Returned when: ``state=absent``, ``state=directory``, ``state=file``
"""
return self.acquire(server, 'path')

Expand Down Expand Up @@ -1138,7 +1138,7 @@ def gid(self, server: str | None = None) -> int:
"""
Group ID of the group.
Returned when: `state` is `present`
Returned when: ``state`` is ``present``
"""
return self.acquire(server, 'gid')

Expand All @@ -1162,7 +1162,7 @@ def system(self, server: str | None = None) -> bool:
"""
Whether the group is a system group or not.
Returned when: `state` is `present`
Returned when: ``state`` is ``present``
"""
return self.acquire(server, 'system')

Expand Down Expand Up @@ -1557,7 +1557,7 @@ class PingResults(RunnerResults):

def ping(self, server: str | None = None) -> str:
"""
Value provided with the `data` parameter.
Value provided with the ``data`` parameter.
Returned when: success
"""
Expand Down Expand Up @@ -2026,7 +2026,7 @@ class SystemdResults(RunnerResults):

def status(self, server: str | None = None) -> dict[str, Incomplete]:
"""
A dictionary with the key=value pairs returned from `systemctl show`.
A dictionary with the key=value pairs returned from ``systemctl show``.
Returned when: success
"""
Expand All @@ -2050,7 +2050,7 @@ class SystemdServiceResults(RunnerResults):

def status(self, server: str | None = None) -> dict[str, Incomplete]:
"""
A dictionary with the key=value pairs returned from `systemctl show`.
A dictionary with the key=value pairs returned from ``systemctl show``.
Returned when: success
"""
Expand Down Expand Up @@ -2228,7 +2228,7 @@ def files(self, server: str | None = None) -> list[Incomplete]:
"""
List of all the files in the archive.
Returned when: `list_files` is `True`
Returned when: ``list_files`` is ``True``
"""
return self.acquire(server, 'files')

Expand Down Expand Up @@ -2286,7 +2286,7 @@ def src(self, server: str | None = None) -> str:
"""
The source archive's path.
If `src` was a remote web URL, or from the local ansible controller,
If ``src`` was a remote web URL, or from the local ansible controller,
this shows the temporary location where the download was stored.
Returned when: always
Expand Down Expand Up @@ -2417,7 +2417,7 @@ def append(self, server: str | None = None) -> bool:
"""
Whether or not to append the user to groups.
Returned when: `state` is `present` and the user exists
Returned when: ``state`` is ``present`` and the user exists
"""
return self.acquire(server, 'append')

Expand All @@ -2441,7 +2441,7 @@ def force(self, server: str | None = None) -> bool:
"""
Whether or not a user account was forcibly deleted.
Returned when: `state` is `absent` and user exists
Returned when: ``state`` is ``absent`` and user exists
"""
return self.acquire(server, 'force')

Expand All @@ -2457,23 +2457,23 @@ def groups(self, server: str | None = None) -> str:
"""
List of groups of which the user is a member.
Returned when: `groups` is not empty and `state` is `present`
Returned when: ``groups`` is not empty and ``state`` is ``present``
"""
return self.acquire(server, 'groups')

def home(self, server: str | None = None) -> str:
"""
Path to user's home directory.
Returned when: `state` is `present`
Returned when: ``state`` is ``present``
"""
return self.acquire(server, 'home')

def move_home(self, server: str | None = None) -> bool:
"""
Whether or not to move an existing home directory.
Returned when: `state` is `present` and user exists
Returned when: ``state`` is ``present`` and user exists
"""
return self.acquire(server, 'move_home')

Expand All @@ -2489,47 +2489,47 @@ def password(self, server: str | None = None) -> str:
"""
Masked value of the password.
Returned when: `state` is `present` and `password` is not empty
Returned when: ``state`` is ``present`` and ``password`` is not empty
"""
return self.acquire(server, 'password')

def remove(self, server: str | None = None) -> bool:
"""
Whether or not to remove the user account.
Returned when: `state` is `absent` and user exists
Returned when: ``state`` is ``absent`` and user exists
"""
return self.acquire(server, 'remove')

def shell(self, server: str | None = None) -> str:
"""
User login shell.
Returned when: `state` is `present`
Returned when: ``state`` is ``present``
"""
return self.acquire(server, 'shell')

def ssh_fingerprint(self, server: str | None = None) -> str:
"""
Fingerprint of generated SSH key.
Returned when: `generate_ssh_key` is `True`
Returned when: ``generate_ssh_key`` is ``True``
"""
return self.acquire(server, 'ssh_fingerprint')

def ssh_key_file(self, server: str | None = None) -> str:
"""
Path to generated SSH private key file.
Returned when: `generate_ssh_key` is `True`
Returned when: ``generate_ssh_key`` is ``True``
"""
return self.acquire(server, 'ssh_key_file')

def ssh_public_key(self, server: str | None = None) -> str:
"""
Generated SSH public key file.
Returned when: `generate_ssh_key` is `True`
Returned when: ``generate_ssh_key`` is ``True``
"""
return self.acquire(server, 'ssh_public_key')

Expand All @@ -2553,7 +2553,7 @@ def system(self, server: str | None = None) -> bool:
"""
Whether or not the account is a system account.
Returned when: `system` is passed to the module and the account does
Returned when: ``system`` is passed to the module and the account does
not exist
"""
return self.acquire(server, 'system')
Expand All @@ -2562,7 +2562,7 @@ def uid(self, server: str | None = None) -> int:
"""
User ID of the user account.
Returned when: `uid` is passed to the module
Returned when: ``uid`` is passed to the module
"""
return self.acquire(server, 'uid')

Expand Down Expand Up @@ -3461,7 +3461,7 @@ def user(self, server: str | None = None) -> str:
def validate_certs(self, server: str | None = None) -> bool:
"""
This only applies if using a https url as the source of the keys. If
set to `false`, the SSL certificates will not be validated.
set to ``false``, the SSL certificates will not be validated.
Returned when: success
"""
Expand Down Expand Up @@ -3504,7 +3504,7 @@ class FirewalldInfoResults(RunnerResults):

def active_zones(self, server: str | None = None) -> bool:
"""
Gather active zones only if turn it `true`.
Gather active zones only if turn it ``true``.
Returned when: success
"""
Expand All @@ -3520,9 +3520,9 @@ def collected_zones(self, server: str | None = None) -> list[Incomplete]:

def undefined_zones(self, server: str | None = None) -> list[Incomplete]:
"""
A list of undefined zones in `zones` option.
A list of undefined zones in ``zones`` option.
`undefined_zones` will be ignored for gathering process.
``undefined_zones`` will be ignored for gathering process.
Returned when: success
"""
Expand Down Expand Up @@ -4309,7 +4309,8 @@ def values( # type:ignore[override]
) -> dict[str, Incomplete]:
"""
dictionary of before and after values; each key is a variable name,
each value is another dict with `before`, `after`, and `changed` keys.
each value is another dict with ``before``, ``after``, and ``changed``
keys.
Returned when: always
"""
Expand Down Expand Up @@ -4547,19 +4548,19 @@ def name(self, server: str | None = None) -> str:

def added(self, server: str | None = None) -> list[Incomplete]:
"""
A list of members added when `state` is `present` or `pure`; this is
empty if no members are added.
A list of members added when ``state`` is ``present`` or ``pure``;
this is empty if no members are added.
Returned when: success and `state` is `present`
Returned when: success and ``state`` is ``present``
"""
return self.acquire(server, 'added')

def removed(self, server: str | None = None) -> list[Incomplete]:
"""
A list of members removed when `state` is `absent` or `pure`; this is
empty if no members are removed.
A list of members removed when ``state`` is ``absent`` or ``pure``;
this is empty if no members are removed.
Returned when: success and `state` is `absent`
Returned when: success and ``state`` is ``absent``
"""
return self.acquire(server, 'removed')

Expand Down Expand Up @@ -4766,7 +4767,7 @@ class WinPowershellResults(RunnerResults):

def result(self, server: str | None = None) -> Incomplete:
"""
The values that were set by `$Ansible.Result` in the script.
The values that were set by ``$Ansible.Result`` in the script.
Defaults to an empty dict but can be set to anything by the script.
Expand Down Expand Up @@ -4817,7 +4818,7 @@ def warning(self, server: str | None = None) -> list[Incomplete]:
"""
A list of warning messages created by the script.
Warning messages only appear when `$WarningPreference = 'Continue'`.
Warning messages only appear when ``$WarningPreference = 'Continue'``.
Returned when: always
"""
Expand All @@ -4827,7 +4828,7 @@ def verbose(self, server: str | None = None) -> list[Incomplete]:
"""
A list of warning messages created by the script.
Verbose messages only appear when `$VerbosePreference = 'Continue'`.
Verbose messages only appear when ``$VerbosePreference = 'Continue'``.
Returned when: always
"""
Expand All @@ -4837,7 +4838,7 @@ def debug(self, server: str | None = None) -> list[Incomplete]:
"""
A list of warning messages created by the script.
Debug messages only appear when `$DebugPreference = 'Continue'`.
Debug messages only appear when ``$DebugPreference = 'Continue'``.
Returned when: always
"""
Expand Down Expand Up @@ -5359,8 +5360,8 @@ def reboot_required(self, server: str | None = None) -> bool:

def rebooted(self, server: str | None = None) -> bool:
"""
Set to `true` when the target Windows host has been rebooted by
`win_updates`.
Set to ``true`` when the target Windows host has been rebooted by
``win_updates``.
Returned when: success
"""
Expand All @@ -5370,7 +5371,7 @@ def updates(self, server: str | None = None) -> dict[str, Incomplete]:
"""
Updates that were found/installed.
The key for each update is the `id` of the update.
The key for each update is the ``id`` of the update.
Returned when: success
"""
Expand Down Expand Up @@ -5726,8 +5727,8 @@ def label(self, server: str | None = None) -> Incomplete:

def impersonation_level(self, server: str | None = None) -> str:
"""
The impersonation level of the token, only valid if `token_type` is
`TokenImpersonation`, see
The impersonation level of the token, only valid if ``token_type`` is
``TokenImpersonation``, see
`reference <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379572.aspx>`__.
Returned when: success
Expand Down
Loading

0 comments on commit 444d7f6

Please sign in to comment.