[PATCH] Use Sphinx syntax for docstrings
Vratislav Podzimek
vpodzime at redhat.com
Fri Apr 5 08:16:28 UTC 2013
The old syntax for docstrings came from the epydoc which is now more or less a
dead project. We use Sphinx syntax for the documentation of new code.
Signed-off-by: Vratislav Podzimek <vpodzime at redhat.com>
---
pyanaconda/exception.py | 6 +--
pyanaconda/flags.py | 4 +-
pyanaconda/iutil.py | 8 ++--
pyanaconda/keyboard.py | 66 +++++++++++++++---------------
pyanaconda/localization.py | 10 ++---
pyanaconda/network.py | 6 +--
pyanaconda/ntp.py | 24 +++++------
pyanaconda/safe_dbus.py | 58 +++++++++++++-------------
pyanaconda/timezone.py | 18 ++++----
pyanaconda/ui/gui/__init__.py | 4 +-
pyanaconda/ui/gui/spokes/datetime_spoke.py | 10 ++---
pyanaconda/ui/gui/spokes/welcome.py | 2 +-
12 files changed, 108 insertions(+), 108 deletions(-)
diff --git a/pyanaconda/exception.py b/pyanaconda/exception.py
index 352fecf..1da8d00 100644
--- a/pyanaconda/exception.py
+++ b/pyanaconda/exception.py
@@ -49,8 +49,8 @@ class AnacondaExceptionHandler(ExceptionHandler):
def __init__(self, confObj, intfClass, exnClass, tty_num):
"""
- @see: python-meh's ExceptionHandler
- @param tty_num: the number of tty the interface is running on
+ :see: python-meh's ExceptionHandler
+ :param tty_num: the number of tty the interface is running on
"""
@@ -64,7 +64,7 @@ class AnacondaExceptionHandler(ExceptionHandler):
Helper function with one argument only so that it can be registered
with GLib.idle_add() to run on idle.
- @type dump_info: an instance of the meh.DumpInfo class
+ :type dump_info: an instance of the meh.DumpInfo class
"""
diff --git a/pyanaconda/flags.py b/pyanaconda/flags.py
index 5538266..2a26e2f 100644
--- a/pyanaconda/flags.py
+++ b/pyanaconda/flags.py
@@ -180,8 +180,8 @@ def can_touch_runtime_system(msg):
"""
Guard that should be used before doing actions that modify runtime system.
- @param msg: message to be logged in case that runtime system cannot be touched
- @rtype: bool
+ :param msg: message to be logged in case that runtime system cannot be touched
+ :rtype: bool
"""
diff --git a/pyanaconda/iutil.py b/pyanaconda/iutil.py
index 43b9b99..fcce3af 100644
--- a/pyanaconda/iutil.py
+++ b/pyanaconda/iutil.py
@@ -371,7 +371,7 @@ def _run_systemctl(command, service):
"""
Runs 'systemctl command service.service'
- @return: exit status of the systemctl
+ :return: exit status of the systemctl
"""
@@ -423,9 +423,9 @@ def vtActivate(num):
"""
Try to switch to tty number $num.
- @type num: int
- @return: whether the switch was successful or not
- @rtype: bool
+ :type num: int
+ :return: whether the switch was successful or not
+ :rtype: bool
"""
diff --git a/pyanaconda/keyboard.py b/pyanaconda/keyboard.py
index 978a790..eae0508 100755
--- a/pyanaconda/keyboard.py
+++ b/pyanaconda/keyboard.py
@@ -57,8 +57,8 @@ def _parse_layout_variant(layout):
Parse layout and variant from the string that may look like 'layout' or
'layout (variant)'.
- @return: the (layout, variant) pair, where variant can be ""
- @rtype: tuple
+ :return: the (layout, variant) pair, where variant can be ""
+ :rtype: tuple
"""
@@ -77,10 +77,10 @@ def _join_layout_variant(layout, variant=""):
Join layout and variant to form the commonly used 'layout (variant)'
or 'layout' (if variant is missing) format.
- @type layout: string
- @type variant: string
- @return: 'layout (variant)' or 'layout' string
- @rtype: string
+ :type layout: string
+ :type variant: string
+ :return: 'layout (variant)' or 'layout' string
+ :rtype: string
"""
@@ -93,8 +93,8 @@ def get_layouts_xorg_conf(keyboard):
"""
Get the xorg.conf content setting up layouts in the ksdata.
- @param keyboard: ksdata.keyboard object
- @rtype: str
+ :param keyboard: ksdata.keyboard object
+ :rtype: str
"""
@@ -139,7 +139,7 @@ def populate_missing_items(keyboard):
they are missing. By invoking LocaledWrapper's methods this function
MODIFIES CONFIGURATION FILES.
- @type keyboard: ksdata.keyboard object
+ :type keyboard: ksdata.keyboard object
"""
@@ -161,11 +161,11 @@ def write_keyboard_config(keyboard, root, convert=True, weight=0):
$root/etc/X11/xorg.conf.d/01-anaconda-layouts.conf and
$root/etc/vconsole.conf.
- @param keyboard: ksdata.keyboard object
- @param root: path to the root of the installed system
- @param convert: whether to convert specified values to get the missing
+ :param keyboard: ksdata.keyboard object
+ :param root: path to the root of the installed system
+ :param convert: whether to convert specified values to get the missing
ones
- @param weight: weight (prefix) of the xorg.conf file written out
+ :param weight: weight (prefix) of the xorg.conf file written out
"""
@@ -208,7 +208,7 @@ def dracut_setup_args(keyboard):
"""
Function returning dracut setup args for the given keyboard configuration.
- @type keyboard: ksdata.keyboard object
+ :type keyboard: ksdata.keyboard object
"""
@@ -226,9 +226,9 @@ def _try_to_load_keymap(keymap):
successfull or not. It can be used to test if given string is VConsole
keymap or not, but in case it is given valid keymap, IT REALLY LOADS IT!.
- @type keymap: string
- @raise KeyboardConfigError: if loadkeys command is not available
- @return: True if given string was a valid keymap and thus was loaded,
+ :type keymap: string
+ :raise KeyboardConfigError: if loadkeys command is not available
+ :return: True if given string was a valid keymap and thus was loaded,
False otherwise
"""
@@ -251,8 +251,8 @@ def activate_keyboard(keyboard):
"""
Try to setup VConsole keymap and X11 layouts as specified in kickstart.
- @param keyboard: ksdata.keyboard object
- @type keyboard: ksdata.keyboard object
+ :param keyboard: ksdata.keyboard object
+ :type keyboard: ksdata.keyboard object
"""
@@ -504,7 +504,7 @@ class XklWrapper(object):
"""
Get current activated X layout's name
- @return: current activated X layout's name (e.g. "Czech (qwerty)")
+ :return: current activated X layout's name (e.g. "Czech (qwerty)")
"""
@@ -538,8 +538,8 @@ class XklWrapper(object):
were zipped) are used for the construction of real layouts (e.g.
'cz (qwerty)').
- @param layout: either 'layout' or 'layout (variant)'
- @raise XklWrapperError: if the given layout cannot be added
+ :param layout: either 'layout' or 'layout (variant)'
+ :raise XklWrapperError: if the given layout cannot be added
"""
@@ -564,8 +564,8 @@ class XklWrapper(object):
See also the documentation for the add_layout method.
- @param layout: either 'layout' or 'layout (variant)'
- @raise XklWrapperError: if the given layout cannot be removed
+ :param layout: either 'layout' or 'layout (variant)'
+ :raise XklWrapperError: if the given layout cannot be removed
"""
@@ -594,9 +594,9 @@ class XklWrapper(object):
Method that replaces the layouts defined in the current X configuration
with the new ones given.
- @param layouts_list: list of layouts defined as either 'layout' or
+ :param layouts_list: list of layouts defined as either 'layout' or
'layout (variant)'
- @raise XklWrapperError: if layouts cannot be replaced with the new ones
+ :raise XklWrapperError: if layouts cannot be replaced with the new ones
"""
@@ -620,9 +620,9 @@ class XklWrapper(object):
Method that sets options for layout switching. It replaces the old
options with the new ones.
- @param options: layout switching options to be set
- @type options: list or generator
- @raise XklWrapperError: if the old options cannot be replaced with the
+ :param options: layout switching options to be set
+ :type options: list or generator
+ :raise XklWrapperError: if the old options cannot be replaced with the
new ones
"""
@@ -660,9 +660,9 @@ class LocaledWrapper(object):
Method that sets VConsole keymap and returns X11 layout and
variant that (systemd-localed thinks) match given keymap best.
- @return: string containing "layout (variant)" or "layout" if variant
+ :return: string containing "layout (variant)" or "layout" if variant
is missing
- @rtype: string
+ :rtype: string
"""
@@ -699,8 +699,8 @@ class LocaledWrapper(object):
and returns VConsole keymap that (systemd-localed thinks) matches
given layout and variant best.
- @return: a keymap matching layout and variant best
- @rtype: string
+ :return: a keymap matching layout and variant best
+ :rtype: string
"""
diff --git a/pyanaconda/localization.py b/pyanaconda/localization.py
index 672e35c..38c5a76 100644
--- a/pyanaconda/localization.py
+++ b/pyanaconda/localization.py
@@ -48,9 +48,9 @@ class LocaleInfo(object):
def __init__(self, localedata, encoding="", script=""):
"""
- @param encoding: encoding from the locale specification, e.g. UTF-8
+ :param encoding: encoding from the locale specification, e.g. UTF-8
(localedata object has no attribute for that)
- @param script: script from the locale specification (e.g. latin)
+ :param script: script from the locale specification (e.g. latin)
(changing localedata.script attribute results in
problems)
@@ -227,7 +227,7 @@ def expand_langs(astring):
"fr", "fr_FR", "fr_FR.UTF-8 at euro", "fr.UTF-8 at euro", "fr_FR at euro",
"fr_FR.UTF-8", "fr at euro", "fr.UTF-8"
- @rtype: list of strings
+ :rtype: list of strings
"""
@@ -290,8 +290,8 @@ def write_language_configuration(lang, root):
"""
Write language configuration to the $root/etc/locale.conf file.
- @param lang: ksdata.lang object
- @param root: path to the root of the installed system
+ :param lang: ksdata.lang object
+ :param root: path to the root of the installed system
"""
diff --git a/pyanaconda/network.py b/pyanaconda/network.py
index 48cad2b..b13426f 100644
--- a/pyanaconda/network.py
+++ b/pyanaconda/network.py
@@ -82,10 +82,10 @@ def sanityCheckHostname(hostname):
"""
Check if the given string is (syntactically) a valid hostname.
- @param hostname: a string to check
- @returns: a pair containing boolean value (valid or invalid) and
+ :param hostname: a string to check
+ :returns: a pair containing boolean value (valid or invalid) and
an error message (if applicable)
- @rtype: (bool, str)
+ :rtype: (bool, str)
"""
diff --git a/pyanaconda/ntp.py b/pyanaconda/ntp.py
index 0da3e1f..61e9a6a 100644
--- a/pyanaconda/ntp.py
+++ b/pyanaconda/ntp.py
@@ -46,7 +46,7 @@ def ntp_server_working(server):
"""
Runs rdate to try to connect to the $server (timeout may take some time).
- @return: True if the given server is reachable and working, False otherwise
+ :return: True if the given server is reachable and working, False otherwise
"""
@@ -64,8 +64,8 @@ def get_servers_from_config(conf_file_path=NTP_CONFIG_FILE,
Goes through the chronyd's configuration file looking for lines starting
with 'server'.
- @return: servers found in the chronyd's configuration
- @rtype: list
+ :return: servers found in the chronyd's configuration
+ :rtype: list
"""
@@ -92,8 +92,8 @@ def save_servers_to_config(servers, conf_file_path=NTP_CONFIG_FILE,
the given ones. If the out_file is not None, then it is used for the
resulting config.
- @type servers: iterable
- @param out_file_path: path to the file used for the resulting config
+ :type servers: iterable
+ :param out_file_path: path to the file used for the resulting config
"""
@@ -157,10 +157,10 @@ def one_time_sync(server, callback=None):
function is blocking and will not return until the time gets synced or
querying server fails (may take some time before timeouting).
- @param server: NTP server
- @param callback: callback function to run after sync or failure
- @type callback: a function taking one boolean argument (success)
- @return: True if the sync was successful, False otherwise
+ :param server: NTP server
+ :param callback: callback function to run after sync or failure
+ :type callback: a function taking one boolean argument (success)
+ :return: True if the sync was successful, False otherwise
"""
@@ -180,9 +180,9 @@ def one_time_sync_async(server, callback=None):
returns. Use callback argument to specify the function called when the
new thread finishes if needed.
- @param server: NTP server
- @param callback: callback function to run after sync or failure
- @type callback: a function taking one boolean argument (success)
+ :param server: NTP server
+ :param callback: callback function to run after sync or failure
+ :type callback: a function taking one boolean argument (success)
"""
diff --git a/pyanaconda/safe_dbus.py b/pyanaconda/safe_dbus.py
index 0e39820..67798b6 100644
--- a/pyanaconda/safe_dbus.py
+++ b/pyanaconda/safe_dbus.py
@@ -51,22 +51,22 @@ def dbus_call_safe_sync(service, obj_path, iface, method, args,
new connection is established. Safely means that it is a synchronous,
thread-safe call not using any main loop.
- @param service: DBus service to use
- @type service: str
- @param obj_path: object path of the object to call method on
- @type obj_path: str
- @param iface: interface to use
- @type iface: str
- @param method: name of the method to call
- @type method: str
- @param args: arguments to pass to the method
- @type args: GVariant
- @param connection: connection to use (if None, a new connection is
+ :param service: DBus service to use
+ :type service: str
+ :param obj_path: object path of the object to call method on
+ :type obj_path: str
+ :param iface: interface to use
+ :type iface: str
+ :param method: name of the method to call
+ :type method: str
+ :param args: arguments to pass to the method
+ :type args: GVariant
+ :param connection: connection to use (if None, a new connection is
established)
- @type connection: Gio.DBusConnection
- @return: unpacked value returned by the method
- @rtype: tuple with elements that depend on the method
- @raise DBusCallError: if some DBus related error appears
+ :type connection: Gio.DBusConnection
+ :return: unpacked value returned by the method
+ :rtype: tuple with elements that depend on the method
+ :raise DBusCallError: if some DBus related error appears
"""
@@ -96,22 +96,22 @@ def dbus_get_property_safe_sync(service, obj_path, iface, prop_name,
"""
Get value of a given property of a given object provided by a given service.
- @param service: DBus service to use
- @type service: str
- @param obj_path: object path
- @type obj_path: str
- @param iface: interface to use
- @type iface: str
- @param prop_name: name of the property
- @type prop_name: str
- @param connection: connection to use (if None, a new connection is
+ :param service: DBus service to use
+ :type service: str
+ :param obj_path: object path
+ :type obj_path: str
+ :param iface: interface to use
+ :type iface: str
+ :param prop_name: name of the property
+ :type prop_name: str
+ :param connection: connection to use (if None, a new connection is
established)
- @type connection: Gio.DBusConnection
- @return: unpacked value of the property
- @rtype: tuple with elements that depend on the type of the property
- @raise DBusCallError: when the internal dbus_call_safe_sync invocation
+ :type connection: Gio.DBusConnection
+ :return: unpacked value of the property
+ :rtype: tuple with elements that depend on the type of the property
+ :raise DBusCallError: when the internal dbus_call_safe_sync invocation
raises an exception
- @raise DBusPropertyError: when the given object doesn't have the given
+ :raise DBusPropertyError: when the given object doesn't have the given
property
"""
diff --git a/pyanaconda/timezone.py b/pyanaconda/timezone.py
index 2e436c2..67234a1 100644
--- a/pyanaconda/timezone.py
+++ b/pyanaconda/timezone.py
@@ -55,9 +55,9 @@ def write_timezone_config(timezone, root):
"""
Write timezone configuration for the system specified by root.
- @param timezone: ksdata.timezone object
- @param root: path to the root
- @raise: TimezoneConfigError
+ :param timezone: ksdata.timezone object
+ :param root: path to the root
+ :raise: TimezoneConfigError
"""
@@ -105,7 +105,7 @@ def save_hw_clock(timezone):
"""
Save system time to HW clock.
- @param timezone: ksdata.timezone object
+ :param timezone: ksdata.timezone object
"""
@@ -126,7 +126,7 @@ def get_all_territory_timezones(territory):
"""
Return the list of timezones for a given territory.
- @param territory: either localization.LocaleInfo or territory
+ :param territory: either localization.LocaleInfo or territory
"""
@@ -148,7 +148,7 @@ def get_preferred_timezone(territory):
simply returns the first timezone in the list of timezones for a given
territory.
- @param territory: either localization.LocaleInfo or territory
+ :param territory: either localization.LocaleInfo or territory
"""
@@ -163,7 +163,7 @@ def get_all_regions_and_timezones():
"""
Get a dictionary mapping the regions to the list of their timezones.
- @rtype: dict
+ :rtype: dict
"""
@@ -184,8 +184,8 @@ def is_valid_timezone(timezone):
"""
Check if a given string is an existing timezone.
- @type timezone: str
- @rtype: bool
+ :type timezone: str
+ :rtype: bool
"""
diff --git a/pyanaconda/ui/gui/__init__.py b/pyanaconda/ui/gui/__init__.py
index 37e347b..f8efb7f 100644
--- a/pyanaconda/ui/gui/__init__.py
+++ b/pyanaconda/ui/gui/__init__.py
@@ -502,9 +502,9 @@ class GraphicalExceptionHandlingIface(meh.ui.gui.GraphicalIntf):
def __init__(self, lightbox_func):
"""
- @param lightbox_func: a function that creates lightbox for a given
+ :param lightbox_func: a function that creates lightbox for a given
window
- @type lightbox_func: GtkWindow -> None
+ :type lightbox_func: GtkWindow -> None
"""
diff --git a/pyanaconda/ui/gui/spokes/datetime_spoke.py b/pyanaconda/ui/gui/spokes/datetime_spoke.py
index 37a60b0..b760346 100644
--- a/pyanaconda/ui/gui/spokes/datetime_spoke.py
+++ b/pyanaconda/ui/gui/spokes/datetime_spoke.py
@@ -174,7 +174,7 @@ class NTPconfigDialog(GUIObject):
If the server is working, set its data to SERVER_OK, otherwise set its
data to SERVER_NOK.
- @param itr: iterator of the $server's row in the self._serversStore
+ :param itr: iterator of the $server's row in the self._serversStore
"""
@@ -185,7 +185,7 @@ class NTPconfigDialog(GUIObject):
the MainLoop with thread-safe GLib.idle_add (but only with one
argument).
- @param arg_tuple: (store, itr, column, value)
+ :param arg_tuple: (store, itr, column, value)
"""
@@ -228,7 +228,7 @@ class NTPconfigDialog(GUIObject):
Checks if a given server is a valid hostname and if yes, adds it
to the list of servers.
- @param server: string containing hostname
+ :param server: string containing hostname
"""
@@ -653,7 +653,7 @@ class DatetimeSpoke(FirstbootSpokeMixIn, NormalSpoke):
"""
Get the selected item of the combobox.
- @return: selected item or None
+ :return: selected item or None
"""
@@ -737,7 +737,7 @@ class DatetimeSpoke(FirstbootSpokeMixIn, NormalSpoke):
def on_region_changed(self, combo, *args):
"""
- @see: on_city_changed
+ :see: on_city_changed
"""
diff --git a/pyanaconda/ui/gui/spokes/welcome.py b/pyanaconda/ui/gui/spokes/welcome.py
index 1f150c2..402ff05 100644
--- a/pyanaconda/ui/gui/spokes/welcome.py
+++ b/pyanaconda/ui/gui/spokes/welcome.py
@@ -79,7 +79,7 @@ class LanguageMixIn(object):
"""
Set default keyboard settings (layouts, layout switching).
- @param lang_name: name of the selected language (e.g. "Czech")
+ :param lang_name: name of the selected language (e.g. "Czech")
"""
--
1.7.11.7
More information about the anaconda-patches
mailing list