mirror of
https://github.com/saltstack/salt.git
synced 2025-04-17 10:10:20 +00:00
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.
This commit is contained in:
Elias Probst
Daniel Wozniak
parent
14d89b6ae3
commit
e681745c09
1 changed files with 76 additions and 71 deletions
|
|
@ -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 <salt.modules.system.halt>`,
|
||||
:mod:`system.poweroff <salt.modules.system.poweroff>`,
|
||||
:mod:`system.reboot <salt.modules.system.reboot>`, and
|
||||
:mod:`system.shutdown <salt.modules.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 <salt.modules.system.set_system_date>` and
|
||||
:mod:`system.set_system_time <salt.modules.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 <mm-dd-yy> format for the date.
|
||||
Set the system date. Use ``<mm-dd-yy>`` 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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue