Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve gui documentation

Browse Source
This commit is contained in:
Nick Hall 2013-11-14 18:05:42 +00:00
parent 2e746a21da
commit 5e1cd88bcb
11 changed files with 110 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/api.rst
View File

@ -2,7 +2,7 @@
Code Documentation 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 The :mod:`gen` Module
======================= =======================
@ -22,7 +22,7 @@ Contents:
gen/gen_proxy gen/gen_proxy
gen/gen_utils gen/gen_utils
The GRAMPS Application The Gramps Application
======================== ========================
Contents: Contents:
@ -36,7 +36,7 @@ Contents:
relationship relationship
simple simple
Usefull snippets Useful snippets
=================== ===================
Contents: Contents:

6
docs/coregui/gui.rst
View File

@ -154,7 +154,7 @@ Filter Editor
:show-inheritance: :show-inheritance:
***************************** *****************************
Gramps Bar Gramplet Bar
***************************** *****************************
.. automodule:: gramps.gui.widgets.grampletbar .. automodule:: gramps.gui.widgets.grampletbar
.. autoclass:: DetachedWindow .. autoclass:: DetachedWindow
@ -180,7 +180,7 @@ Navigator
:show-inheritance: :show-inheritance:
***************************** *****************************
Plugins Manager Plugin Manager
***************************** *****************************
.. automodule:: gramps.gui.pluginmanager .. automodule:: gramps.gui.pluginmanager
.. autoclass:: GuiPluginManager .. autoclass:: GuiPluginManager
@ -215,7 +215,7 @@ Utils
:show-inheritance: :show-inheritance:
***************************** *****************************
Views Manager View Manager
***************************** *****************************
.. automodule:: gramps.gui.viewmanager .. automodule:: gramps.gui.viewmanager
.. autoclass:: ViewManager .. autoclass:: ViewManager

16
gramps/gui/aboutdialog.py
View File

@ -157,11 +157,11 @@ def ellipses(text):
# #
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
class AuthorParser(handler.ContentHandler): 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 The ``authors.xml`` file has the same format as the one in the `svn2cl
<http://ch.tudelft.nl/~arthur/svn2cl/>} package, with an additional <http://ch.tudelft.nl/~arthur/svn2cl/>`_ package, with an additional
C{title} tag in the C{author} element. For example:: ``title`` tag in the ``author`` element. For example::
<author uid="dallingham" title="author"> <author uid="dallingham" title="author">
Don Allingham &lt;<html:a href="mailto:don@gramps-project.org">don@gramps-project.org</html:a>&gt; Don Allingham &lt;<html:a href="mailto:don@gramps-project.org">don@gramps-project.org</html:a>&gt;
@ -211,11 +211,11 @@ class AuthorParser(handler.ContentHandler):
def _get_authors(): def _get_authors():
"""Return all the authors and contributors in a string. """Return all the authors and contributors in a string.
Parse the C{authors.xml} file if found, or return the default Parse the ``authors.xml`` file if found, or return the default
list from L{const} module in case of I/O or parsing failure. 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 If the ``authors.xml`` file is successfully parsed the *Authors* and
I{Contributors} are grouped separately with an appropriate header. *Contributors* are grouped separately with an appropriate header.
""" """
try: try:

17
gramps/gui/dbguielement.py
View File

@ -21,7 +21,8 @@
# $Id$ # $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 * connect to db signals
* listen to db changes to update themself on relevant changes * listen to db changes to update themself on relevant changes
* determine if the GUI has become out of sync with the db * 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): 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. Most interaction with the DB should be done via the callman attribute.
On initialization, the method _connect_db_signals is called. Inheriting On initialization, the method :meth:`_connect_db_signals` is called.
objects are advised to group the setup of the callman attribute here. Inheriting objects are advised to group the setup of the callman attribute
here.
.. attribute callman : a `~gen.utils.callman.CallbackManager` object, to .. attribute callman: a :class:`.CallbackManager` object, to be used to
be used to track specific changes in the db and set up callbacks track specific changes in the db and set up callbacks
""" """
def __init__(self, database): def __init__(self, database):
self.callman = CallbackManager(database) self.callman = CallbackManager(database)

6
gramps/gui/editors/editdate.py
View File

@ -22,7 +22,7 @@
# $Id$ # $Id$
""" """
Date editing module for GRAMPS. Date editing module for Gramps.
The EditDate provides visual feedback to the user via a pixamp The EditDate provides visual feedback to the user via a pixamp
to indicate if the associated GtkEntry box contains a valid date. Green 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): class EditDate(ManagedWindow):
""" """
Dialog allowing to build the date precisely, to correct possible 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): def __init__(self, date, uistate, track):
@ -228,7 +228,7 @@ class EditDate(ManagedWindow):
def build_menu_names(self, obj): 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) return (_("Date selection"), None)

6
gramps/gui/editors/filtereditor.py
View File

@ -692,7 +692,7 @@ class EditRule(ManagedWindow):
def on_help_clicked(self, obj): def on_help_clicked(self, obj):
""" """
Display the relevant portion of GRAMPS manual. Display the relevant portion of Gramps manual.
""" """
display_help() display_help()
@ -807,7 +807,7 @@ class EditFilter(ManagedWindow):
self.show() self.show()
def on_help_clicked(self, obj): 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) display_help(webpage=WIKI_HELP_PAGE)
def close_window(self, obj): def close_window(self, obj):
@ -1064,7 +1064,7 @@ class FilterEditor(ManagedWindow):
return (_("Custom Filter Editor"), _("Custom Filter Editor")) return (_("Custom Filter Editor"), _("Custom Filter Editor"))
def help_clicked(self, obj): def help_clicked(self, obj):
"""Display the relevant portion of GRAMPS manual""" """Display the relevant portion of Gramps manual"""
display_help() display_help()
def filter_select_row(self, obj): def filter_select_row(self, obj):

34
gramps/gui/pluginmanager.py
View File

@ -21,7 +21,7 @@
# $Id$ # $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 from specified directories and provide information about the loaded
plugins. plugins.
@ -58,13 +58,13 @@ from gramps.gen.const import ICON
def base_reg_stock_icons(iconpaths, extraiconsize, items): def base_reg_stock_icons(iconpaths, extraiconsize, items):
""" """
Reusable base to register stock icons in Gramps Reusable base to register stock icons in Gramps
..attribute iconpaths: list of main directory of the base icon, and :param iconpaths: list of main directory of the base icon, and extension,
extension, eg: eg:
[(os.path.join(IMAGE_DIR, 'scalable'), '.svg')] [(os.path.join(IMAGE_DIR, 'scalable'), '.svg')]
..attribute extraiconsize: list of dir with extra prepared icon sizes and :param extraiconsize: list of dir with extra prepared icon sizes and the
the gtk size to use them for, eg: gtk size to use them for, eg:
[(os.path.join(IMAGE_DIR, '22x22'), Gtk.IconSize.LARGE_TOOLBAR)] [(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, '')] [('gramps-db', _('Family Trees'), Gdk.ModifierType.CONTROL_MASK, 0, '')]
""" """
@ -168,20 +168,22 @@ class GuiPluginManager(Callback):
def load_icons(self, icons, dir): 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. plugin.
..attribute icons: The plugin directory must contain the directories scalable, 48x48, 22x22
New stock icons to register. A list of tuples (stock_id, icon_label), and 16x16 with the icons, e.g. in dir we have:
eg:
- 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', _('My Plugin')),
('gramps_myplugin_open', _('Open Plugin'))] ('gramps_myplugin_open', _('Open Plugin'))]
The plugin directory must contain the directories scalable, 48x48, 22x22 :type icons: A list of tuples (stock_id, icon_label)
and 16x16 with the icons, eg in dir we have: :param dir: Directory from where to load the icons
scalable/gramps_myplugin.svg :type dir: str
48x48/gramps_myplugin.png
22x22/gramps_myplugin.png
..attribute dir: directory from where to load the icons
""" """
if win(): if win():
iconpaths = [ iconpaths = [

67
gramps/gui/user.py
View File

@ -48,7 +48,7 @@ from .dialog import (WarningDialog, ErrorDialog, DBErrorDialog,
class User(user.User): class User(user.User):
""" """
This class provides a means to interact with the user via GTK. 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): def __init__(self, callback=None, error=None, uistate=None):
user.User.__init__(self, callback, error) user.User.__init__(self, callback, error)
@ -59,15 +59,15 @@ class User(user.User):
""" """
Start showing a progress indicator to the user. Start showing a progress indicator to the user.
@param title: the title of the progress meter :param title: the title of the progress meter
@type title: str :type title: str
@param message: the message associated with the progress meter :param message: the message associated with the progress meter
@type message: str :type message: str
@param steps: the total number of steps for the progress meter. :param steps: the total number of steps for the progress meter.
a value of 0 indicates that the ending is unknown and the a value of 0 indicates that the ending is unknown and the
meter should just show activity. meter should just show activity.
@type steps: int :type steps: int
@returns: none :returns: none
""" """
self._progress = ProgressMeter(title) self._progress = ProgressMeter(title)
if steps > 0: if steps > 0:
@ -94,18 +94,19 @@ class User(user.User):
""" """
Prompt the user with a message to select an alternative. Prompt the user with a message to select an alternative.
@param title: the title of the question, e.g.: "Undo history warning" :param title: the title of the question, e.g.: "Undo history warning"
@type title: str :type title: str
@param message: the message, e.g.: "Proceeding with the tool will :param message: the message, e.g.: "Proceeding with the tool will erase
erase the undo history. If you think you may want to revert the undo history. If you think you may want to revert
running this tool, please stop here and make a backup of the DB." running this tool, please stop here and make a backup
@type question: str of the DB."
@param accept_label: what to call the positive choice, e.g.: "Proceed" :type question: str
@type accept_label: str :param accept_label: what to call the positive choice, e.g.: "Proceed"
@param reject_label: what to call the negative choice, e.g.: "Stop" :type accept_label: str
@type reject_label: str :param reject_label: what to call the negative choice, e.g.: "Stop"
@returns: the user's answer to the question :type reject_label: str
@rtype: bool :returns: the user's answer to the question
:rtype: bool
""" """
dialog = QuestionDialog2(title, message, accept_label, reject_label) dialog = QuestionDialog2(title, message, accept_label, reject_label)
return dialog.run() return dialog.run()
@ -114,11 +115,11 @@ class User(user.User):
""" """
Warn the user. Warn the user.
@param title: the title of the warning :param title: the title of the warning
@type title: str :type title: str
@param warning: the warning :param warning: the warning
@type warning: str :type warning: str
@returns: none :returns: none
""" """
WarningDialog(title, warning) WarningDialog(title, warning)
@ -126,11 +127,11 @@ class User(user.User):
""" """
Notify the user of an error. Notify the user of an error.
@param title: the title of the error :param title: the title of the error
@type title: str :type title: str
@param error: the error message :param error: the error message
@type error: str :type error: str
@returns: none :returns: none
""" """
if self.error_function: if self.error_function:
self.error_function(title, error) self.error_function(title, error)
@ -141,9 +142,9 @@ class User(user.User):
""" """
Notify the user of a DB error. Notify the user of a DB error.
@param error: the DB error message :param error: the DB error message
@type error: str :type error: str
@returns: none :returns: none
""" """
DBErrorDialog(error) DBErrorDialog(error)

34
gramps/gui/utils.py
View File

@ -109,18 +109,18 @@ class CLIDialog:
class ProgressMeter(object): class ProgressMeter(object):
""" """
Progress meter class for GRAMPS. Progress meter class for Gramps.
The progress meter has two modes: The progress meter has two modes:
MODE_FRACTION is used when you know the number of steps that will be taken. 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. 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 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 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 the bar to the other. Then, call :meth:`step` as many times as you want. The
will move from left to right until you stop calling step. bar will move from left to right until you stop calling :meth:`step`.
""" """
MODE_FRACTION = 0 MODE_FRACTION = 0
@ -328,12 +328,14 @@ class SystemFonts(object):
The bug is described here: https://bugzilla.gnome.org/show_bug.cgi?id=679654 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: /usr/local/lib/python2.7/site-packages/gi/types.py:47:
Warning: g_value_get_object: assertion `G_VALUE_HOLDS_OBJECT (value)' failed 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() To get a list of fonts, instantiate this class and call
#TODO GTK3: the underlying bug may be fixed at some point in the future :meth:`get_system_fonts`
.. todo:: GTK3: the underlying bug may be fixed at some point in the future
""" """
__FONTS = None __FONTS = None
@ -383,9 +385,11 @@ def poll_external (args):
GLib.timeout_add_seconds, so the arguments are in a tuple because that GLib.timeout_add_seconds, so the arguments are in a tuple because that
function takes only a single data argument. function takes only a single data argument.
@proc the process, returned from subprocess.Popen() :param proc: the process, returned from subprocess.Popen()
@errorstrings a dict of possible response values and the corresponding messages to display. :param errorstrings: a dict of possible response values and the
@returns bool returned to timeout_add_seconds: should this function be called again? corresponding messages to display.
:return: bool returned to timeout_add_seconds: should this function be
called again?
""" """
(proc, errorstrings) = args (proc, errorstrings) = args
resp = proc.poll() 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 whatever program is configured on the host as the default program for that
type of file. type of file.
@param file_path: The path to the file to be opened. :param file_path: The path to the file to be opened.
Example: "c:\\foo.txt" Example: "c:\\foo.txt"
@type file_path: string :type file_path: string
@return: nothing :return: nothing
""" """
errstrings = None errstrings = None
@ -472,9 +476,9 @@ def is_right_click(event):
def color_graph_box(alive=False, gender=Person.MALE): def color_graph_box(alive=False, gender=Person.MALE):
""" """
Returns based on the config the color for graph boxes in hex :return: based on the config the color for graph boxes in hex
If gender is None, an empty box is assumed If gender is None, an empty box is assumed
Return type: tuple (hex color fill, hex color border) :rtype: tuple (hex color fill, hex color border)
""" """
if gender == Person.MALE: if gender == Person.MALE:
if alive: if alive:

7
gramps/gui/viewmanager.py
View File

@ -243,19 +243,18 @@ WIKI_HELP_PAGE_MAN = '%s' % URL_MANUAL_PAGE
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
class ViewManager(CLIManager): class ViewManager(CLIManager):
""" """
Overview **Overview**
========
The ViewManager is the session manager of the program. The ViewManager is the session manager of the program.
Specifically, it manages the main window of the program. It is closely tied Specifically, it manages the main window of the program. It is closely tied
into the Gtk.UIManager to control all menus and actions. 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 Views are organised in categories. The categories can be accessed via
a sidebar. Within a category, the different views are accesible via the a sidebar. Within a category, the different views are accesible via the
toolbar of view menu. 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 window. Each view is separate from the others, and has no knowledge of
the others. the others.

2
gramps/gui/widgets/grampletbar.py
View File

@ -664,7 +664,7 @@ class DetachedWindow(ManagedWindow):
def build_menu_names(self, obj): def build_menu_names(self, obj):
""" """
Part of the GRAMPS window interface. Part of the Gramps window interface.
""" """
return (self.title, 'Gramplet') return (self.title, 'Gramplet')