From e681745c09c30a164c0604a9c14d7f8f3d0b5b97 Mon Sep 17 00:00:00 2001 From: Elias Probst Date: Sat, 28 Nov 2020 22:39:22 +0000 Subject: [PATCH] modules.system: improve documentation consistency Make better/more consistent use of rST features, such as: - use "verbatim" for inline code/variables - reference module functions using `:mod:` - fix syntax (e.g. missing empty line before list) Furthermore, improve the wording (prevent personal pronouns), spelling (e.g. use upper-cased acronyms such as `CLI` or `POSIX`) and grammar. --- salt/modules/system.py | 147 +++++++++++++++++++++-------------------- 1 file changed, 76 insertions(+), 71 deletions(-) diff --git a/salt/modules/system.py b/salt/modules/system.py index 784892c337a..18c062878b4 100644 --- a/salt/modules/system.py +++ b/salt/modules/system.py @@ -3,13 +3,13 @@ Support for reboot, shutdown, etc on POSIX-like systems. .. note:: - If you have configured a wrapper such as ``molly-guard`` to - intercept *interactive* shutdown commands, be aware that calling - ``system.halt``, ``system.poweroff``, ``system.reboot``, and - ``system.shutdown`` with ``salt-call`` will hang indefinitely - while the wrapper script waits for user input. Calling them with - ``salt`` will work as expected. - + If a wrapper such as ``molly-guard`` to intercept *interactive* shutdown + commands is configured, calling :mod:`system.halt `, + :mod:`system.poweroff `, + :mod:`system.reboot `, and + :mod:`system.shutdown ` with ``salt-call`` will + hang indefinitely while the wrapper script waits for user input. Calling them + with ``salt`` will work as expected. """ import os.path @@ -28,7 +28,7 @@ __virtualname__ = "system" def __virtual__(): """ Only supported on POSIX-like systems - Windows, Solaris, and Mac have their own modules + Windows, Solaris, and OS X have their own modules """ if salt.utils.platform.is_windows(): return (False, "This module is not available on Windows") @@ -137,7 +137,7 @@ def _date_bin_set_datetime(new_date): """ set the system date/time using the date command - Note using a strictly posix-compliant date binary we can only set the date + Note using a strictly POSIX-compliant date binary we can only set the date up to the minute. """ cmd = ["date"] @@ -176,7 +176,7 @@ def _date_bin_set_datetime(new_date): def has_settable_hwclock(): """ - Returns True if the system has a hardware clock capable of being + Returns ``True`` if the system has a hardware clock capable of being set from software. CLI Example: @@ -211,13 +211,13 @@ def _swclock_to_hwclock(): def _try_parse_datetime(time_str, fmts): """ - Attempts to parse the input time_str as a date. + Attempts to parse the input ``time_str`` as a date. :param str time_str: A string representing the time :param list fmts: A list of date format strings. - :return: Returns a datetime object if parsed properly. Otherwise None - :rtype datetime: + :return: Returns a datetime object if parsed properly. Otherwise ``None`` + :rtype: datetime """ result = None for fmt in fmts: @@ -231,9 +231,9 @@ def _try_parse_datetime(time_str, fmts): def _offset_to_min(utc_offset): """ - Helper function that converts the utc offset string into number of minutes - offset. Input is in form "[+-]?HHMM". Example valid inputs are "+0500" - "-0300" and "0800". These would return -300, 180, 480 respectively. + Helper function that converts the UTC offset string into number of minutes + offset. Input is in form ``[+-]?HHMM``. Example valid inputs are ``+0500`` + ``-0300`` and ``0800``. These would return ``-300``, ``180``, ``480`` respectively. """ match = re.match(r"^([+-])?(\d\d)(\d\d)$", utc_offset) if not match: @@ -250,7 +250,7 @@ def _get_offset_time(utc_offset): """ Will return the current time adjusted using the input timezone offset. - :rtype datetime: + :rtype: datetime """ if utc_offset is not None: minutes = _offset_to_min(utc_offset) @@ -266,12 +266,12 @@ def get_system_time(utc_offset=None): """ Get the system time. - :param str utc_offset: The utc offset in 4 digit (+0600) format with an - optional sign (+/-). Will default to None which will use the local - timezone. To set the time based off of UTC use "'+0000'". Note: if + :param str utc_offset: The UTC offset in 4 digit (e.g. ``+0600``) format with an + optional sign (``+``/``-``). Will default to ``None`` which will use the local + timezone. To set the time based off of UTC use ``+0000``. Note: If being passed through the command line will need to be quoted twice to - allow negative offsets. - :return: Returns the system time in HH:MM:SS AM/PM format. + allow negative offsets (e.g. ``"'+0000'"``). + :return: Returns the system time in ``HH:MM:SS AM/PM`` format. :rtype: str CLI Example: @@ -290,22 +290,23 @@ def set_system_time(newtime, utc_offset=None): :param str newtime: The time to set. Can be any of the following formats. - - HH:MM:SS AM/PM - - HH:MM AM/PM - - HH:MM:SS (24 hour) - - HH:MM (24 hour) - Note that the salt command line parser parses the date/time - before we obtain the argument (preventing us from doing utc) + - ``HH:MM:SS AM/PM`` + - ``HH:MM AM/PM`` + - ``HH:MM:SS`` (24 hour) + - ``HH:MM`` (24 hour) + + Note that the Salt command line parser parses the date/time + before we obtain the argument (preventing us from doing UTC) Therefore the argument must be passed in as a string. - Meaning you may have to quote the text twice from the command line. + Meaning the text might have to be quoted twice on the command line. - :param str utc_offset: The utc offset in 4 digit (+0600) format with an - optional sign (+/-). Will default to None which will use the local - timezone. To set the time based off of UTC use "'+0000'". Note: if + :param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an + optional sign (``+``/``-``). Will default to ``None`` which will use the local + timezone. To set the time based off of UTC use ``+0000``. Note: If being passed through the command line will need to be quoted twice to - allow negative offsets. - :return: Returns True if successful. Otherwise False. + allow negative offsets (e.g. ``"'+0000'"``) + :return: Returns ``True`` if successful. Otherwise ``False``. :rtype: bool CLI Example: @@ -331,12 +332,12 @@ def get_system_date_time(utc_offset=None): """ Get the system date/time. - :param str utc_offset: The utc offset in 4 digit (+0600) format with an - optional sign (+/-). Will default to None which will use the local - timezone. To set the time based off of UTC use "'+0000'". Note: if + :param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an + optional sign (``+``/``-``). Will default to ``None`` which will use the local + timezone. To set the time based off of UTC use ``+0000``. Note: If being passed through the command line will need to be quoted twice to - allow negative offsets. - :return: Returns the system time in YYYY-MM-DD hh:mm:ss format. + allow negative offsets (e.g. ``"'+0000'"``). + :return: Returns the system time in ``YYYY-MM-DD hh:mm:ss`` format. :rtype: str CLI Example: @@ -361,25 +362,26 @@ def set_system_date_time( """ Set the system date and time. Each argument is an element of the date, but not required. If an element is not passed, the current system value for - that element will be used. For example, if you don't pass the year, the - current system year will be used. (Used by set_system_date and - set_system_time) + that element will be used. For example, if the year is not passed, the + current system year will be used. (Used by + :mod:`system.set_system_date ` and + :mod:`system.set_system_time `) Updates hardware clock, if present, in addition to software (kernel) clock. - :param int years: Years digit, ie: 2015 - :param int months: Months digit: 1 - 12 - :param int days: Days digit: 1 - 31 - :param int hours: Hours digit: 0 - 23 - :param int minutes: Minutes digit: 0 - 59 - :param int seconds: Seconds digit: 0 - 59 - :param str utc_offset: The utc offset in 4 digit (+0600) format with an - optional sign (+/-). Will default to None which will use the local - timezone. To set the time based off of UTC use "'+0000'". Note: if + :param int years: Years digit, e.g.: ``2015`` + :param int months: Months digit: ``1``-``12`` + :param int days: Days digit: ``1``-``31`` + :param int hours: Hours digit: ``0``-``23`` + :param int minutes: Minutes digit: ``0``-``59`` + :param int seconds: Seconds digit: ``0``-``59`` + :param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an + optional sign (``+``/``-``). Will default to ``None`` which will use the local + timezone. To set the time based off of UTC use ``+0000``. Note: If being passed through the command line will need to be quoted twice to - allow negative offsets. - :return: True if successful. Otherwise False. + allow negative offsets (e.g. ``"'+0000'"``). + :return: ``True`` if successful. Otherwise ``False``. :rtype: bool CLI Example: @@ -427,11 +429,11 @@ def get_system_date(utc_offset=None): """ Get the system date - :param str utc_offset: The utc offset in 4 digit (+0600) format with an - optional sign (+/-). Will default to None which will use the local - timezone. To set the time based off of UTC use "'+0000'". Note: if + :param str utc_offset: The UTC offset in 4 digit (``+0600``) format with an + optional sign (``+``/``-``). Will default to ``None`` which will use the local + timezone. To set the time based off of UTC use ``+0000``. Note: If being passed through the command line will need to be quoted twice to - allow negative offsets. + allow negative offsets (e.g. ``"'+0000'"``). :return: Returns the system date. :rtype: str @@ -447,17 +449,17 @@ def get_system_date(utc_offset=None): def set_system_date(newdate, utc_offset=None): """ - Set the system date. Use format for the date. + Set the system date. Use ```` format for the date. :param str newdate: The date to set. Can be any of the following formats: - - YYYY-MM-DD - - MM-DD-YYYY - - MM-DD-YY - - MM/DD/YYYY - - MM/DD/YY - - YYYY/MM/DD + - ``YYYY-MM-DD`` + - ``MM-DD-YYYY`` + - ``MM-DD-YY`` + - ``MM/DD/YYYY`` + - ``MM/DD/YY`` + - ``YYYY/MM/DD`` CLI Example: @@ -505,7 +507,7 @@ class _FixedOffset(tzinfo): def _strip_quotes(str_q): """ - Helper function to strip off the ' or " off of a string + Helper function to strip off the ``'`` or ``"`` off of a string """ if str_q[0] == str_q[-1] and str_q.startswith(("'", '"')): return str_q[1:-1] @@ -514,11 +516,12 @@ def _strip_quotes(str_q): def get_computer_desc(): """ - Get PRETTY_HOSTNAME value stored in /etc/machine-info + Get ``PRETTY_HOSTNAME`` value stored in ``/etc/machine-info`` If this file doesn't exist or the variable doesn't exist - return False. + return ``False``. - :return: Value of PRETTY_HOSTNAME if this does not exist False. + :return: Value of ``PRETTY_HOSTNAME`` in ``/etc/machine-info``. + If file/variable does not exist ``False``. :rtype: str CLI Example: @@ -560,12 +563,12 @@ def get_computer_desc(): def set_computer_desc(desc): """ - Set PRETTY_HOSTNAME value stored in /etc/machine-info + Set ``PRETTY_HOSTNAME`` value stored in ``/etc/machine-info`` This will create the file if it does not exist. If - it is unable to create or modify this file returns False. + it is unable to create or modify this file, ``False`` is returned. :param str desc: The computer description - :return: False on failure. True if successful. + :return: ``False`` on failure. ``True`` if successful. CLI Example: @@ -662,6 +665,8 @@ def set_reboot_required_witnessed(): Returns: bool: ``True`` if successful, otherwise ``False`` + CLI Example: + .. code-block:: bash salt '*' system.set_reboot_required_witnessed