[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