From 5e1cd88bcb93e4048668ed90c729d0fc2b97eb19 Mon Sep 17 00:00:00 2001 From: Nick Hall Date: Thu, 14 Nov 2013 18:05:42 +0000 Subject: [PATCH] Improve gui documentation --- docs/api.rst | 6 +-- docs/coregui/gui.rst | 6 +-- gramps/gui/aboutdialog.py | 16 +++---- gramps/gui/dbguielement.py | 17 +++---- gramps/gui/editors/editdate.py | 6 +-- gramps/gui/editors/filtereditor.py | 6 +-- gramps/gui/pluginmanager.py | 42 +++++++++--------- gramps/gui/user.py | 71 +++++++++++++++--------------- gramps/gui/utils.py | 38 +++++++++------- gramps/gui/viewmanager.py | 7 ++- gramps/gui/widgets/grampletbar.py | 2 +- 11 files changed, 110 insertions(+), 107 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index eb74b8208..654ac2193 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -2,7 +2,7 @@ Code Documentation ################## -*GRAMPS* provides several general API. The most important is the *gen* module, providing access to all code that can be of interest outside of the GRAMPS program. +*Gramps* provides several general API. The most important is the *gen* module, providing access to all code that can be of interest outside of the Gramps program. The :mod:`gen` Module ======================= @@ -22,7 +22,7 @@ Contents: gen/gen_proxy gen/gen_utils -The GRAMPS Application +The Gramps Application ======================== Contents: @@ -36,7 +36,7 @@ Contents: relationship simple -Usefull snippets +Useful snippets =================== Contents: diff --git a/docs/coregui/gui.rst b/docs/coregui/gui.rst index cff8f0b38..e86bbdb76 100644 --- a/docs/coregui/gui.rst +++ b/docs/coregui/gui.rst @@ -154,7 +154,7 @@ Filter Editor :show-inheritance: ***************************** -Gramps Bar +Gramplet Bar ***************************** .. automodule:: gramps.gui.widgets.grampletbar .. autoclass:: DetachedWindow @@ -180,7 +180,7 @@ Navigator :show-inheritance: ***************************** -Plugins Manager +Plugin Manager ***************************** .. automodule:: gramps.gui.pluginmanager .. autoclass:: GuiPluginManager @@ -215,7 +215,7 @@ Utils :show-inheritance: ***************************** -Views Manager +View Manager ***************************** .. automodule:: gramps.gui.viewmanager .. autoclass:: ViewManager diff --git a/gramps/gui/aboutdialog.py b/gramps/gui/aboutdialog.py index 5a4be4e56..3cb9ba2b1 100644 --- a/gramps/gui/aboutdialog.py +++ b/gramps/gui/aboutdialog.py @@ -157,11 +157,11 @@ def ellipses(text): # #------------------------------------------------------------------------- class AuthorParser(handler.ContentHandler): - """Parse the 'authors.xml file to show in the About dialog. + """Parse the ``authors.xml`` file to show in the About dialog. - The C{authors.xml} file has the same format as the one in the U{svn2cl - } package, with an additional - C{title} tag in the C{author} element. For example:: + The ``authors.xml`` file has the same format as the one in the `svn2cl + `_ package, with an additional + ``title`` tag in the ``author`` element. For example:: Don Allingham <don@gramps-project.org> @@ -211,11 +211,11 @@ class AuthorParser(handler.ContentHandler): def _get_authors(): """Return all the authors and contributors in a string. - Parse the C{authors.xml} file if found, or return the default - list from L{const} module in case of I/O or parsing failure. + Parse the ``authors.xml`` file if found, or return the default + list from :mod:`.const` module in case of I/O or parsing failure. - If the C{authors.xml} file is successfully parsed the I{Authors} and - I{Contributors} are grouped separately with an appropriate header. + If the ``authors.xml`` file is successfully parsed the *Authors* and + *Contributors* are grouped separately with an appropriate header. """ try: diff --git a/gramps/gui/dbguielement.py b/gramps/gui/dbguielement.py index bb75180a9..16747ab62 100644 --- a/gramps/gui/dbguielement.py +++ b/gramps/gui/dbguielement.py @@ -21,7 +21,8 @@ # $Id$ """ -Group common stuff GRAMPS GUI elements must be able to do when tracking a DB: +Group common stuff Gramps GUI elements must be able to do when tracking a DB: + * connect to db signals * listen to db changes to update themself on relevant changes * determine if the GUI has become out of sync with the db @@ -41,17 +42,13 @@ from gramps.gen.utils.callman import CallbackManager #------------------------------------------------------------------------- class DbGUIElement(object): """ - Group common stuff GRAMPS GUI elements must be able to do when tracking - a DB: - * connect to db signals - * listen to db changes to update themself on relevant changes - * determine if the GUI has become out of sync with the db Most interaction with the DB should be done via the callman attribute. - On initialization, the method _connect_db_signals is called. Inheriting - objects are advised to group the setup of the callman attribute here. + On initialization, the method :meth:`_connect_db_signals` is called. + Inheriting objects are advised to group the setup of the callman attribute + here. - .. attribute callman : a `~gen.utils.callman.CallbackManager` object, to - be used to track specific changes in the db and set up callbacks + .. attribute callman: a :class:`.CallbackManager` object, to be used to + track specific changes in the db and set up callbacks """ def __init__(self, database): self.callman = CallbackManager(database) diff --git a/gramps/gui/editors/editdate.py b/gramps/gui/editors/editdate.py index f3c365708..da48d9840 100644 --- a/gramps/gui/editors/editdate.py +++ b/gramps/gui/editors/editdate.py @@ -22,7 +22,7 @@ # $Id$ """ -Date editing module for GRAMPS. +Date editing module for Gramps. The EditDate provides visual feedback to the user via a pixamp to indicate if the associated GtkEntry box contains a valid date. Green @@ -109,7 +109,7 @@ WIKI_HELP_SEC = _('manual|Editing_Dates') class EditDate(ManagedWindow): """ Dialog allowing to build the date precisely, to correct possible - limitations of parsing and/or underlying structure of Date. + limitations of parsing and/or underlying structure of :class:`.Date`. """ def __init__(self, date, uistate, track): @@ -228,7 +228,7 @@ class EditDate(ManagedWindow): def build_menu_names(self, obj): """ - Define the menu entry for the ManagedWindows + Define the menu entry for the :class:`.ManagedWindow` """ return (_("Date selection"), None) diff --git a/gramps/gui/editors/filtereditor.py b/gramps/gui/editors/filtereditor.py index d1d863ddf..a9d3d2fc2 100644 --- a/gramps/gui/editors/filtereditor.py +++ b/gramps/gui/editors/filtereditor.py @@ -692,7 +692,7 @@ class EditRule(ManagedWindow): def on_help_clicked(self, obj): """ - Display the relevant portion of GRAMPS manual. + Display the relevant portion of Gramps manual. """ display_help() @@ -807,7 +807,7 @@ class EditFilter(ManagedWindow): self.show() def on_help_clicked(self, obj): - """Display the relevant portion of GRAMPS manual""" + """Display the relevant portion of Gramps manual""" display_help(webpage=WIKI_HELP_PAGE) def close_window(self, obj): @@ -1064,7 +1064,7 @@ class FilterEditor(ManagedWindow): return (_("Custom Filter Editor"), _("Custom Filter Editor")) def help_clicked(self, obj): - """Display the relevant portion of GRAMPS manual""" + """Display the relevant portion of Gramps manual""" display_help() def filter_select_row(self, obj): diff --git a/gramps/gui/pluginmanager.py b/gramps/gui/pluginmanager.py index ff094bd92..ee39b3de1 100644 --- a/gramps/gui/pluginmanager.py +++ b/gramps/gui/pluginmanager.py @@ -21,7 +21,7 @@ # $Id$ """ -The core of the GRAMPS plugin system. This module provides capability to load +The core of the Gramps plugin system. This module provides capability to load plugins from specified directories and provide information about the loaded plugins. @@ -58,13 +58,13 @@ from gramps.gen.const import ICON def base_reg_stock_icons(iconpaths, extraiconsize, items): """ Reusable base to register stock icons in Gramps - ..attribute iconpaths: list of main directory of the base icon, and - extension, eg: - [(os.path.join(IMAGE_DIR, 'scalable'), '.svg')] - ..attribute extraiconsize: list of dir with extra prepared icon sizes and - the gtk size to use them for, eg: + :param iconpaths: list of main directory of the base icon, and extension, + eg: + [(os.path.join(IMAGE_DIR, 'scalable'), '.svg')] + :param extraiconsize: list of dir with extra prepared icon sizes and the + gtk size to use them for, eg: [(os.path.join(IMAGE_DIR, '22x22'), Gtk.IconSize.LARGE_TOOLBAR)] - ..attribute items: list of icons to register, eg: + :param items: list of icons to register, eg: [('gramps-db', _('Family Trees'), Gdk.ModifierType.CONTROL_MASK, 0, '')] """ @@ -168,20 +168,22 @@ class GuiPluginManager(Callback): def load_icons(self, icons, dir): """ - Load icons in the iconfactory of gramps, so they can be used in the + Load icons in the iconfactory of Gramps, so they can be used in the plugin. - - ..attribute icons: - New stock icons to register. A list of tuples (stock_id, icon_label), - eg: - [('gramps_myplugin', _('My Plugin')), - ('gramps_myplugin_open', _('Open Plugin'))] - The plugin directory must contain the directories scalable, 48x48, 22x22 - and 16x16 with the icons, eg in dir we have: - scalable/gramps_myplugin.svg - 48x48/gramps_myplugin.png - 22x22/gramps_myplugin.png - ..attribute dir: directory from where to load the icons + + The plugin directory must contain the directories scalable, 48x48, 22x22 + and 16x16 with the icons, e.g. in dir we have: + + - scalable/gramps_myplugin.svg + - 48x48/gramps_myplugin.png + - 22x22/gramps_myplugin.png + + :param icons: New stock icons to register. e.g. + [('gramps_myplugin', _('My Plugin')), + ('gramps_myplugin_open', _('Open Plugin'))] + :type icons: A list of tuples (stock_id, icon_label) + :param dir: Directory from where to load the icons + :type dir: str """ if win(): iconpaths = [ diff --git a/gramps/gui/user.py b/gramps/gui/user.py index 5e0124902..35ad103c8 100644 --- a/gramps/gui/user.py +++ b/gramps/gui/user.py @@ -48,7 +48,7 @@ from .dialog import (WarningDialog, ErrorDialog, DBErrorDialog, class User(user.User): """ This class provides a means to interact with the user via GTK. - It implements the interface in gramps.gen.user.User() + It implements the interface in :class:`.gen.user.User` """ def __init__(self, callback=None, error=None, uistate=None): user.User.__init__(self, callback, error) @@ -59,15 +59,15 @@ class User(user.User): """ Start showing a progress indicator to the user. - @param title: the title of the progress meter - @type title: str - @param message: the message associated with the progress meter - @type message: str - @param steps: the total number of steps for the progress meter. - a value of 0 indicates that the ending is unknown and the - meter should just show activity. - @type steps: int - @returns: none + :param title: the title of the progress meter + :type title: str + :param message: the message associated with the progress meter + :type message: str + :param steps: the total number of steps for the progress meter. + a value of 0 indicates that the ending is unknown and the + meter should just show activity. + :type steps: int + :returns: none """ self._progress = ProgressMeter(title) if steps > 0: @@ -94,18 +94,19 @@ class User(user.User): """ Prompt the user with a message to select an alternative. - @param title: the title of the question, e.g.: "Undo history warning" - @type title: str - @param message: the message, e.g.: "Proceeding with the tool will - erase the undo history. If you think you may want to revert - running this tool, please stop here and make a backup of the DB." - @type question: str - @param accept_label: what to call the positive choice, e.g.: "Proceed" - @type accept_label: str - @param reject_label: what to call the negative choice, e.g.: "Stop" - @type reject_label: str - @returns: the user's answer to the question - @rtype: bool + :param title: the title of the question, e.g.: "Undo history warning" + :type title: str + :param message: the message, e.g.: "Proceeding with the tool will erase + the undo history. If you think you may want to revert + running this tool, please stop here and make a backup + of the DB." + :type question: str + :param accept_label: what to call the positive choice, e.g.: "Proceed" + :type accept_label: str + :param reject_label: what to call the negative choice, e.g.: "Stop" + :type reject_label: str + :returns: the user's answer to the question + :rtype: bool """ dialog = QuestionDialog2(title, message, accept_label, reject_label) return dialog.run() @@ -114,11 +115,11 @@ class User(user.User): """ Warn the user. - @param title: the title of the warning - @type title: str - @param warning: the warning - @type warning: str - @returns: none + :param title: the title of the warning + :type title: str + :param warning: the warning + :type warning: str + :returns: none """ WarningDialog(title, warning) @@ -126,11 +127,11 @@ class User(user.User): """ Notify the user of an error. - @param title: the title of the error - @type title: str - @param error: the error message - @type error: str - @returns: none + :param title: the title of the error + :type title: str + :param error: the error message + :type error: str + :returns: none """ if self.error_function: self.error_function(title, error) @@ -141,9 +142,9 @@ class User(user.User): """ Notify the user of a DB error. - @param error: the DB error message - @type error: str - @returns: none + :param error: the DB error message + :type error: str + :returns: none """ DBErrorDialog(error) diff --git a/gramps/gui/utils.py b/gramps/gui/utils.py index e6261f150..2cff018bc 100644 --- a/gramps/gui/utils.py +++ b/gramps/gui/utils.py @@ -109,18 +109,18 @@ class CLIDialog: class ProgressMeter(object): """ - Progress meter class for GRAMPS. + Progress meter class for Gramps. The progress meter has two modes: MODE_FRACTION is used when you know the number of steps that will be taken. - Set the total number of steps, and then call step() that many times. + Set the total number of steps, and then call :meth:`step` that many times. The progress bar will progress from left to right. MODE_ACTIVITY is used when you don't know the number of steps that will be taken. Set up the total number of steps for the bar to get from one end of - the bar to the other. Then, call step() as many times as you want. The bar - will move from left to right until you stop calling step. + the bar to the other. Then, call :meth:`step` as many times as you want. The + bar will move from left to right until you stop calling :meth:`step`. """ MODE_FRACTION = 0 @@ -328,12 +328,14 @@ class SystemFonts(object): The bug is described here: https://bugzilla.gnome.org/show_bug.cgi?id=679654 - This code generate a warning: + This code generates a warning: /usr/local/lib/python2.7/site-packages/gi/types.py:47: Warning: g_value_get_object: assertion `G_VALUE_HOLDS_OBJECT (value)' failed - To get a list of fonts, instantiate this class and call get_system_fonts() - #TODO GTK3: the underlying bug may be fixed at some point in the future + To get a list of fonts, instantiate this class and call + :meth:`get_system_fonts` + + .. todo:: GTK3: the underlying bug may be fixed at some point in the future """ __FONTS = None @@ -383,9 +385,11 @@ def poll_external (args): GLib.timeout_add_seconds, so the arguments are in a tuple because that function takes only a single data argument. - @proc the process, returned from subprocess.Popen() - @errorstrings a dict of possible response values and the corresponding messages to display. - @returns bool returned to timeout_add_seconds: should this function be called again? + :param proc: the process, returned from subprocess.Popen() + :param errorstrings: a dict of possible response values and the + corresponding messages to display. + :return: bool returned to timeout_add_seconds: should this function be + called again? """ (proc, errorstrings) = args resp = proc.poll() @@ -402,10 +406,10 @@ def open_file_with_default_application(path): whatever program is configured on the host as the default program for that type of file. - @param file_path: The path to the file to be opened. - Example: "c:\\foo.txt" - @type file_path: string - @return: nothing + :param file_path: The path to the file to be opened. + Example: "c:\\foo.txt" + :type file_path: string + :return: nothing """ errstrings = None @@ -472,9 +476,9 @@ def is_right_click(event): def color_graph_box(alive=False, gender=Person.MALE): """ - Returns based on the config the color for graph boxes in hex - If gender is None, an empty box is assumed - Return type: tuple (hex color fill, hex color border) + :return: based on the config the color for graph boxes in hex + If gender is None, an empty box is assumed + :rtype: tuple (hex color fill, hex color border) """ if gender == Person.MALE: if alive: diff --git a/gramps/gui/viewmanager.py b/gramps/gui/viewmanager.py index 0331dcd89..0b5f04fe3 100644 --- a/gramps/gui/viewmanager.py +++ b/gramps/gui/viewmanager.py @@ -243,19 +243,18 @@ WIKI_HELP_PAGE_MAN = '%s' % URL_MANUAL_PAGE #------------------------------------------------------------------------- class ViewManager(CLIManager): """ - Overview - ======== + **Overview** The ViewManager is the session manager of the program. Specifically, it manages the main window of the program. It is closely tied into the Gtk.UIManager to control all menus and actions. - The ViewManager controls the various Views within the GRAMPS programs. + The ViewManager controls the various Views within the Gramps programs. Views are organised in categories. The categories can be accessed via a sidebar. Within a category, the different views are accesible via the toolbar of view menu. - A View is a particular way of looking a information in the GRAMPS main + A View is a particular way of looking a information in the Gramps main window. Each view is separate from the others, and has no knowledge of the others. diff --git a/gramps/gui/widgets/grampletbar.py b/gramps/gui/widgets/grampletbar.py index 064c467af..0ff22e4dd 100644 --- a/gramps/gui/widgets/grampletbar.py +++ b/gramps/gui/widgets/grampletbar.py @@ -664,7 +664,7 @@ class DetachedWindow(ManagedWindow): def build_menu_names(self, obj): """ - Part of the GRAMPS window interface. + Part of the Gramps window interface. """ return (self.title, 'Gramplet')