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
##################
*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:

6
docs/coregui/gui.rst
View File

@ -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

16
gramps/gui/aboutdialog.py
View File

@ -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
<http://ch.tudelft.nl/~arthur/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
<http://ch.tudelft.nl/~arthur/svn2cl/>`_ package, with an additional
``title`` tag in the ``author`` element. For example::
<author uid="dallingham" title="author">
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():
"""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:

17
gramps/gui/dbguielement.py
View File

@ -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)

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

@ -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)

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

@ -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):

42
gramps/gui/pluginmanager.py
View File

@ -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 = [

71
gramps/gui/user.py
View File

@ -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)

38
gramps/gui/utils.py
View File

@ -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:

7
gramps/gui/viewmanager.py
View File

@ -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.

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

@ -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')