From 1bd893f9f0840fbc9fd12307449a4ac47eda2f6b Mon Sep 17 00:00:00 2001 From: Nick Hall Date: Tue, 12 Nov 2013 16:28:24 +0000 Subject: [PATCH] Improve gen.plug documentation --- gramps/gen/plug/_docgenplugin.py | 64 +++--- gramps/gen/plug/_export.py | 30 +-- gramps/gen/plug/_gramplet.py | 38 ++-- gramps/gen/plug/_import.py | 24 +-- gramps/gen/plug/_manager.py | 41 ++-- gramps/gen/plug/_options.py | 91 ++++---- gramps/gen/plug/_plugin.py | 20 +- gramps/gen/plug/_pluginreg.py | 93 +++++--- gramps/gen/plug/docbackend/docbackend.py | 70 +++--- gramps/gen/plug/docgen/basedoc.py | 18 +- gramps/gen/plug/docgen/drawdoc.py | 16 +- gramps/gen/plug/docgen/fontstyle.py | 20 +- gramps/gen/plug/docgen/graphdoc.py | 68 +++--- gramps/gen/plug/docgen/paperstyle.py | 38 ++-- gramps/gen/plug/docgen/paragraphstyle.py | 67 +++--- gramps/gen/plug/docgen/stylesheet.py | 40 ++-- gramps/gen/plug/docgen/tablestyle.py | 28 +-- gramps/gen/plug/docgen/textdoc.py | 69 +++--- gramps/gen/plug/menu/_boolean.py | 10 +- gramps/gen/plug/menu/_booleanlist.py | 20 +- gramps/gen/plug/menu/_color.py | 10 +- gramps/gen/plug/menu/_destination.py | 39 ++-- gramps/gen/plug/menu/_enumeratedlist.py | 36 ++-- gramps/gen/plug/menu/_family.py | 10 +- gramps/gen/plug/menu/_filter.py | 18 +- gramps/gen/plug/menu/_media.py | 10 +- gramps/gen/plug/menu/_menu.py | 44 ++-- gramps/gen/plug/menu/_note.py | 10 +- gramps/gen/plug/menu/_number.py | 28 +-- gramps/gen/plug/menu/_option.py | 50 ++--- gramps/gen/plug/menu/_person.py | 10 +- gramps/gen/plug/menu/_personlist.py | 10 +- gramps/gen/plug/menu/_placelist.py | 10 +- gramps/gen/plug/menu/_string.py | 10 +- gramps/gen/plug/menu/_style.py | 14 +- gramps/gen/plug/menu/_surnamecolor.py | 10 +- gramps/gen/plug/menu/_text.py | 10 +- gramps/gen/plug/report/_bibliography.py | 69 +++--- gramps/gen/plug/report/_options.py | 264 +++++++++++++---------- gramps/gen/plug/report/endnotes.py | 40 ++-- gramps/gen/plug/report/utils.py | 42 ++-- 41 files changed, 864 insertions(+), 745 deletions(-) diff --git a/gramps/gen/plug/_docgenplugin.py b/gramps/gen/plug/_docgenplugin.py index 28512daf8..261b7cd32 100644 --- a/gramps/gen/plug/_docgenplugin.py +++ b/gramps/gen/plug/_docgenplugin.py @@ -34,30 +34,30 @@ class DocGenPlugin(Plugin): def __init__(self, name, description, basedoc, paper, style, extension, docoptclass, basedocname): """ - @param name: A friendly name to call this plugin. + :param name: A friendly name to call this plugin. Example: "Plain Text" - @type name: string - @param description: A short description of the plugin. + :type name: string + :param description: A short description of the plugin. Example: "This plugin will generate text documents in plain text." - @type description: string - @param basedoc: A class that implements the BaseDoc + :type description: string + :param basedoc: A class that implements the BaseDoc interface. - @type basedoc: BaseDoc - @param paper: Indicates whether the plugin uses paper or not. + :type basedoc: BaseDoc + :param paper: Indicates whether the plugin uses paper or not. True = use paper; False = do not use paper - @type paper: bool - @param style: Indicates whether the plugin uses styles or not. + :type paper: bool + :param style: Indicates whether the plugin uses styles or not. True = use styles; False = do not use styles - @type style: bool - @param extension: The extension for the output file. + :type style: bool + :param extension: The extension for the output file. Example: "txt" - @type extension: str - @param docoptclass: either None or a subclass of DocOptions - @type docoptclass: either None or a DocOptions subclass - @param basedocname: The BaseDoc name of this plugin. + :type extension: str + :param docoptclass: either None or a subclass of DocOptions + :type docoptclass: either None or a DocOptions subclass + :param basedocname: The BaseDoc name of this plugin. Example: "AsciiDoc" - @type basedocname: string - @return: nothing + :type basedocname: string + :return: nothing """ Plugin.__init__(self, name, description, basedoc.__module__) self.__basedoc = basedoc @@ -69,9 +69,9 @@ class DocGenPlugin(Plugin): def get_basedoc(self): """ - Get the BaseDoc class for this plugin. + Get the :class:`.BaseDoc` class for this plugin. - @return: the BaseDoc class passed into __init__ + :return: the :class:`.BaseDoc` class passed into :meth:`__init__` """ return self.__basedoc @@ -79,7 +79,7 @@ class DocGenPlugin(Plugin): """ Get the paper flag for this plugin. - @return: bool - True = use paper; False = do not use paper + :return: bool - True = use paper; False = do not use paper """ return self.__paper @@ -87,7 +87,7 @@ class DocGenPlugin(Plugin): """ Get the style flag for this plugin. - @return: bool - True = use styles; False = do not use styles + :return: bool - True = use styles; False = do not use styles """ return self.__style @@ -95,40 +95,40 @@ class DocGenPlugin(Plugin): """ Get the file extension for the output file. - @return: str + :return: str """ return self.__extension def get_doc_option_class(self): """ - Get the DocOptions subclass for this plugin, if any + Get the :class:`.DocOptions` subclass for this plugin, if any - @return: the DocOptions subclass passed into __init__ + :return: the :class:`.DocOptions` subclass passed into :meth:`__init__` """ return self.__docoptclass def get_basedocname(self): """ - Get the BaseDoc name for this plugin. + Get the :class:`.BaseDoc` name for this plugin. - @return: the BaseDoc name passed into __init__ + :return: the :class:`.BaseDoc` name passed into :meth:`__init__` """ return self.__basedocname def get_text_support(self): """ - Check if the plugin supports the TextDoc interface. + Check if the plugin supports the :class:`.TextDoc` interface. - @return: bool: True if TextDoc is supported; False if TextDoc is not - supported. + :return: bool: True if :class:`.TextDoc` is supported; False if + :class:`.TextDoc` is not supported. """ return bool(issubclass(self.__basedoc, TextDoc)) def get_draw_support(self): """ - Check if the plugin supports the DrawDoc interface. + Check if the plugin supports the :class:`.DrawDoc` interface. - @return: bool: True if DrawDoc is supported; False if DrawDoc is not - supported. + :return: bool: True if :class:`.DrawDoc` is supported; False if + :class:`.DrawDoc` is not supported. """ return bool(issubclass(self.__basedoc, DrawDoc)) diff --git a/gramps/gen/plug/_export.py b/gramps/gen/plug/_export.py index cdccdce21..bd7eb63a8 100644 --- a/gramps/gen/plug/_export.py +++ b/gramps/gen/plug/_export.py @@ -20,7 +20,7 @@ # $Id$ """ -This module provides the Plugin class for export plugins. +This module provides the :class:`.Plugin` class for export plugins. """ from . import Plugin @@ -32,26 +32,26 @@ class ExportPlugin(Plugin): def __init__(self, name, description, export_function, extension, config=None): """ - @param name: A friendly name to call this plugin. + :param name: A friendly name to call this plugin. Example: "GEDCOM Export" - @type name: string - @param description: A short description of the plugin. + :type name: string + :param description: A short description of the plugin. Example: "This plugin will export a GEDCOM file from database" - @type description: string - @param export_function: A function to call to perform the export. + :type description: string + :param export_function: A function to call to perform the export. The function must take the form: def export_function(database, filename, user, option_box): where: "db" is a Gramps database to import the data into "filename" is the file that the data will be exported to "user" provides UI output (callback, errors, etc) - @type export_function: callable - @param extension: The extension for the output file. + :type export_function: callable + :param extension: The extension for the output file. Example: "ged" - @type extension: str - @param config: Options for the exporter - @type config: tuple (??,??) - @return: nothing + :type extension: str + :param config: Options for the exporter + :type config: tuple (??,??) + :return: nothing """ Plugin.__init__(self, name, description, export_function.__module__) self.__export_func = export_function @@ -62,7 +62,7 @@ class ExportPlugin(Plugin): """ Get the export function for this plugin. - @return: the callable export_function passed into __init__ + :return: the callable export_function passed into :meth:`__init__` """ return self.__export_func @@ -70,7 +70,7 @@ class ExportPlugin(Plugin): """ Get the file extension for the export file. - @return: str + :return: str """ return self.__extension @@ -78,6 +78,6 @@ class ExportPlugin(Plugin): """ Get the config. - @return: (??,??) + :return: (??,??) """ return self.__config diff --git a/gramps/gen/plug/_gramplet.py b/gramps/gen/plug/_gramplet.py index 4a3a6a289..65ccbd211 100644 --- a/gramps/gen/plug/_gramplet.py +++ b/gramps/gen/plug/_gramplet.py @@ -101,7 +101,7 @@ class Gramplet(object): def main(self): # return false finishes """ The main place for the gramplet's code. This is a generator. - Generator which will be run in the background, through update(). + Generator which will be run in the background, through :meth:`update`. """ yield False @@ -188,7 +188,7 @@ class Gramplet(object): def render_text(self, text): """ - Render the given text, given that set_use_markup is on. + Render the given text, given that :meth:`set_use_markup` is on. """ self.gui.render_text(text) @@ -202,9 +202,14 @@ class Gramplet(object): """ Clear and set the text to the given text. Additionally, move the cursor to the position given. Positions are: - 'start': start of textview - 'end': end of textview - 'begin': begin of line, before setting the text. + + ======== ======================================= + Position Description + ======== ======================================= + 'start' start of textview + 'end' end of textview + 'begin' begin of line, before setting the text. + ======== ======================================= """ self.gui.set_text(text, scroll_to) @@ -212,9 +217,14 @@ class Gramplet(object): """ Append the text to the textview. Additionally, move the cursor to the position given. Positions are: - 'start': start of textview - 'end': end of textview - 'begin': begin of line, before setting the text. + + ======== ======================================= + Position Description + ======== ======================================= + 'start' start of textview + 'end' end of textview + 'begin' begin of line, before setting the text. + ======== ======================================= """ self.gui.append_text(text, scroll_to) @@ -246,7 +256,8 @@ class Gramplet(object): def no_wrap(self): """ - The view in gramplet should not wrap. DEPRICATED: use set_wrap instead. + The view in gramplet should not wrap. + DEPRICATED: use :meth:`set_wrap` instead. """ self.set_wrap(False) @@ -272,7 +283,7 @@ class Gramplet(object): def update(self, *args): """ - The main interface for running the main method. + The main interface for running the :meth:`main` method. """ from gi.repository import GObject if ((not self.active or @@ -342,13 +353,13 @@ class Gramplet(object): def pause(self, *args): """ - Pause the main method. + Pause the :meth:`main` method. """ self._pause = True def resume(self, *args): """ - Resume the main method that has previously paused. + Resume the :meth:`main` method that has previously paused. """ from gi.repository import GObject self._pause = False @@ -357,7 +368,8 @@ class Gramplet(object): def update_all(self, *args): """ - Force the main loop to run right now (as opposed to running in background). + Force the main loop to run right now (as opposed to running in + background). """ self._generator = self.main() if isinstance(self._generator, types.GeneratorType): diff --git a/gramps/gen/plug/_import.py b/gramps/gen/plug/_import.py index 11183c352..cebe54a53 100644 --- a/gramps/gen/plug/_import.py +++ b/gramps/gen/plug/_import.py @@ -20,7 +20,7 @@ # $Id$ """ -This module provides the Plugin class for import plugins. +This module provides the :class:`.Plugin` class for import plugins. """ from . import Plugin @@ -31,13 +31,13 @@ class ImportPlugin(Plugin): """ def __init__(self, name, description, import_function, extension): """ - @param name: A friendly name to call this plugin. + :param name: A friendly name to call this plugin. Example: "GEDCOM Import" - @type name: string - @param description: A short description of the plugin. + :type name: string + :param description: A short description of the plugin. Example: "This plugin will import a GEDCOM file into a database" - @type description: string - @param import_function: A function to call to perform the import. + :type description: string + :param import_function: A function to call to perform the import. The function must take the form: def import_function(db, filename, user): where: @@ -45,11 +45,11 @@ class ImportPlugin(Plugin): "filename" is the file that contains data to be imported "user" is an instance of the User class implementing GUI functions (callbacks, errors, warnings, etc) - @type import_function: callable - @param extension: The extension for the files imported by this plugin. + :type import_function: callable + :param extension: The extension for the files imported by this plugin. Example: "ged" - @type extension: str - @return: nothing + :type extension: str + :return: nothing """ Plugin.__init__(self, name, description, import_function.__module__ ) self.__import_func = import_function @@ -59,7 +59,7 @@ class ImportPlugin(Plugin): """ Get the import function for this plugins. - @return: the callable import_function passed into __init__ + :return: the callable import_function passed into :meth:`__init__` """ return self.__import_func @@ -67,6 +67,6 @@ class ImportPlugin(Plugin): """ Get the extension for the files imported by this plugin. - @return: str + :return: str """ return self.__extension diff --git a/gramps/gen/plug/_manager.py b/gramps/gen/plug/_manager.py index 398460b52..c437536b9 100644 --- a/gramps/gen/plug/_manager.py +++ b/gramps/gen/plug/_manager.py @@ -23,7 +23,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. @@ -66,12 +66,14 @@ _UNAVAILABLE = _("No description was provided") # #------------------------------------------------------------------------- class BasePluginManager(object): - """ unique singleton storage class for a PluginManager. """ + """ unique singleton storage class for a :class:`.PluginManager`. """ __instance = None def get_instance(): - """ Use this function to get the instance of the PluginManager """ + """ + Use this function to get the instance of the :class:`.PluginManager` + """ if BasePluginManager.__instance is None: BasePluginManager.__instance = 1 # Set to 1 for __init__() BasePluginManager.__instance = BasePluginManager() @@ -190,8 +192,8 @@ class BasePluginManager(object): def load_plugin(self, pdata): """ - Load a PluginData object. This means import of the python module. - Plugin directories are added to sys path, so files are found + Load a :class:`.PluginData` object. This means import of the python + module. Plugin directories are added to sys path, so files are found """ if pdata.id in self.__loaded_plugins: return self.__loaded_plugins[pdata.id] @@ -338,21 +340,21 @@ class BasePluginManager(object): def get_plugin(self, id): """ - Returns a plugin object from PluginRegister by id. + Returns a plugin object from :class:`.PluginRegister` by id. """ return self.__pgr.get_plugin(id) def get_reg_reports(self, gui=True): """ Return list of registered reports - :Param gui: bool indicating if GUI reports or CLI reports must be - returned + :param gui: bool indicating if GUI reports or CLI reports must be + returned """ return self.__pgr.report_plugins(gui) def get_reg_tools(self, gui=True): """ Return list of registered tools - :Param gui: bool indicating if GUI reports or CLI reports must be - returned + :aram gui: bool indicating if GUI reports or CLI reports must be + returned """ return self.__pgr.tool_plugins(gui) @@ -473,7 +475,7 @@ class BasePluginManager(object): """ Get the list of import plugins. - @return: [gen.plug.ImportPlugin] (a list of ImportPlugin instances) + :return: :class:`.ImportPlugin` (a list of ImportPlugin instances) """ ## TODO: would it not be better to remove ImportPlugin and use ## only PluginData, loading from module when importfunction needed? @@ -496,7 +498,7 @@ class BasePluginManager(object): """ Get the list of export plugins. - @return: [gen.plug.ExportPlugin] (a list of ExportPlugin instances) + :return: :class:`.ExportPlugin` (a list of ExportPlugin instances) """ ## TODO: would it not be better to remove ExportPlugin and use ## only PluginData, loading from module when export/options needed? @@ -524,7 +526,7 @@ class BasePluginManager(object): """ Get the list of docgen plugins. - @return: [gen.plug.DocGenPlugin] (a list of DocGenPlugin instances) + :return: :class:`.DocGenPlugin` (a list of DocGenPlugin instances) """ ## TODO: would it not be better to return list of plugindata, and only ## import those docgen that will then actuallly be needed? @@ -556,7 +558,7 @@ class BasePluginManager(object): """ Get the list of docgen plugin names. - @return: a list of DocGenPlugin names + :return: a list of :class:`.DocGenPlugin` names """ if self.__docgen_names == []: hiddenplugins = config.get("plugin.hiddenplugins") @@ -572,11 +574,12 @@ class BasePluginManager(object): Register a mapping from option to guioption for an option that is not native to Gramps but provided by the plugin writer. This should typically be called during initialisation of a - ReportOptions class. - @param option: the option class - @type option: class that inherits from gen.plug.menu.Option - @param guioption: the gui-option class - @type guioption: class that inherits from Gtk.Widget. + :class:`.ReportOptions` class. + + :param option: the option class + :type option: class that inherits from gen.plug.menu.Option + :param guioption: the gui-option class + :type guioption: class that inherits from Gtk.Widget. """ self.__external_opt_dict[option] = guioption; diff --git a/gramps/gen/plug/_options.py b/gramps/gen/plug/_options.py index e5c78c2eb..6f0e0afaf 100644 --- a/gramps/gen/plug/_options.py +++ b/gramps/gen/plug/_options.py @@ -76,34 +76,38 @@ class OptionList(object): def set_options(self, options): """ Set the whole bunch of options for the OptionList. - @param options: list of options to set. - @type options: list + + :param options: list of options to set. + :type options: list """ self.options = options def get_options(self): """ Return the whole bunch of options for the OptionList. - @returns: list of options - @rtype: list + + :returns: list of options + :rtype: list """ return self.options def set_option(self, name,value): """ Set a particular option in the OptionList. - @param name: name of the option to set. - @type name: str - @param value: value of the option to set. - @type str + + :param name: name of the option to set. + :type name: str + :param value: value of the option to set. + :type value: str """ self.options[name] = value def remove_option(self, name): """ Remove a particular option from the OptionList. - @param name: name of the option to remove. - @type name: str + + :param name: name of the option to remove. + :type name: str """ if name in self.options: del self.options[name] @@ -111,10 +115,11 @@ class OptionList(object): def get_option(self, name): """ Return the value of a particular option in the OptionList. - @param name: name of the option to retrieve - @type name: str - @returns: value associated with the passed option - @rtype: str + + :param name: name of the option to retrieve + :type name: str + :returns: value associated with the passed option + :rtype: str """ return self.options.get(name,None) @@ -132,8 +137,9 @@ class OptionListCollection(object): """ Create an OptionListCollection instance from the list defined in the specified file. - @param filename: XML file that contains option definitions - @type filename: str + + :param filename: XML file that contains option definitions + :type filename: str """ self.filename = os.path.expanduser(filename) @@ -148,37 +154,41 @@ class OptionListCollection(object): def get_option_list_map(self): """ Return the map of module names to option lists. - @returns: Returns the map of module names to option lists. - @rtype: dictionary + + :returns: Returns the map of module names to option lists. + :rtype: dictionary """ return self.option_list_map def get_option_list(self, name): """ Return the option_list associated with the module name - @param name: name associated with the desired module. - @type name: str - @returns: returns the option list associated with the name, - or None of no such option exists - @rtype: str + + :param name: name associated with the desired module. + :type name: str + :returns: returns the option list associated with the name, + or None of no such option exists + :rtype: str """ return self.option_list_map.get(name,None) def get_module_names(self): """ Return a list of all the module names in the OptionListCollection - @returns: returns the list of module names - @rtype: list + + :returns: returns the list of module names + :rtype: list """ return list(self.option_list_map.keys()) def set_option_list(self, name, option_list): """ Add or replaces an option_list in the OptionListCollection. - @param name: name associated with the module to add or replace. - @type name: str - @param option_list: list of options - @type option_list: OptionList + + :param name: name associated with the module to add or replace. + :type name: str + :param option_list: list of options + :type option_list: OptionList """ self.option_list_map[name] = option_list @@ -458,7 +468,7 @@ class Options(object): as True then each string will be preneded with the ordinal number when help is printed on the command line. - NOTE: Both dictionaries must have identical keys. + .. note:: Both dictionaries must have identical keys. """ self.name = name self.person_id = person_id @@ -479,9 +489,9 @@ class Options(object): This method MUST be overridden by modules that define new options. - NOTE: To really have any effect besides looking pretty, each widget - set up here must be also parsed in the parse_user_options() - method below. + .. note:: To really have any effect besides looking pretty, each widget + set up here must be also parsed in the + :meth:`parse_user_options` method below. """ pass @@ -495,8 +505,8 @@ class Options(object): appropriate options_dict values. Otherwise the values will not have any user-visible effect. - NOTE: Any widget parsed here MUST be defined and added to the dialog - in the add_user_options() method above. + .. note:: Any widget parsed here MUST be defined and added to the dialog + in the :meth:`add_user_options` method above. """ pass @@ -507,8 +517,8 @@ class Options(object): #------------------------------------------------------------------------ class MenuOptions(object): """ - Introduction - ============ + **Introduction** + A MenuOptions is used to implement the necessary functions for adding options to a menu. """ @@ -534,9 +544,9 @@ class MenuOptions(object): """ Add the user defined options to the menu. - @param menu: A menu class for the options to belong to. - @type menu: Menu - @return: nothing + :param menu: A menu class for the options to belong to. + :type menu: Menu + :return: nothing """ raise NotImplementedError @@ -567,4 +577,3 @@ class MenuOptions(object): for name in self.menu.get_all_option_names(): option = self.menu.get_option_by_name(name) self.options_dict[name] = option.get_value() - diff --git a/gramps/gen/plug/_plugin.py b/gramps/gen/plug/_plugin.py index 4f1f7cf47..dc1242b6a 100644 --- a/gramps/gen/plug/_plugin.py +++ b/gramps/gen/plug/_plugin.py @@ -31,16 +31,16 @@ class Plugin(object): """ def __init__(self, name, description, module_name): """ - @param name: A friendly name to call this plugin. + :param name: A friendly name to call this plugin. Example: "GEDCOM Import" - @type name: string - @param description: A short description of the plugin. + :type name: string + :param description: A short description of the plugin. Example: "This plugin will import a GEDCOM file into a database" - @type description: string - @param module_name: The name of the module that contains this plugin. + :type description: string + :param module_name: The name of the module that contains this plugin. Example: "gedcom" - @type module_name: string - @return: nothing + :type module_name: string + :return: nothing """ self.__name = name self.__desc = description @@ -50,7 +50,7 @@ class Plugin(object): """ Get the name of this plugin. - @return: a string representing the name of the plugin + :return: a string representing the name of the plugin """ return self.__name @@ -58,7 +58,7 @@ class Plugin(object): """ Get the description of this plugin. - @return: a string that describes the plugin + :return: a string that describes the plugin """ return self.__desc @@ -66,7 +66,7 @@ class Plugin(object): """ Get the name of the module that this plugin lives in. - @return: a string representing the name of the module for this plugin + :return: a string representing the name of the module for this plugin """ return self.__mod_name diff --git a/gramps/gen/plug/_pluginreg.py b/gramps/gen/plug/_pluginreg.py index f748ca8b5..30c08549b 100644 --- a/gramps/gen/plug/_pluginreg.py +++ b/gramps/gen/plug/_pluginreg.py @@ -180,12 +180,14 @@ class PluginData(object): """ This is the base class for all plugin data objects. The workflow is: + 1. plugin manager reads all register files, and stores plugin data objects in a plugin register 2. when plugin is needed, the plugin register creates the plugin, and the manager stores this, after which it can be executed. Attributes present for all plugins + .. attribute:: id A unique identifier for the plugin. This is eg used to store the plugin settings. @@ -234,12 +236,14 @@ class PluginData(object): reverts to the plugindirectory itself. Attributes for RELCALC plugins: + .. attribute:: relcalcclass The class in the module that is the relationcalc class .. attribute:: lang_list List of languages this plugin handles Attributes for REPORT plugins: + .. attribute:: require_active Bool, If the reports requries an active person to be set or not .. attribute:: reportclass @@ -248,6 +252,7 @@ class PluginData(object): The report modes: list of REPORT_MODE_GUI ,REPORT_MODE_BKI,REPORT_MODE_CLI Attributes for REPORT and TOOL and QUICKREPORT and VIEW plugins + .. attribute:: category Or the report category the plugin belongs to, default=CATEGORY_TEXT or the tool category a plugin belongs to, default=TOOL_UTILS @@ -256,16 +261,19 @@ class PluginData(object): default=("Miscellaneous", _("Miscellaneous")) Attributes for REPORT and TOOL and DOCGEN plugins + .. attribute:: optionclass The class in the module that is the option class Attributes for TOOL plugins + .. attribute:: toolclass The class in the module that is the tool class .. attribute:: tool_modes The tool modes: list of TOOL_MODE_GUI, TOOL_MODE_CLI Attributes for DOCGEN plugins + .. attribute :: docclass The class in the module that is the BaseDoc defined .. attribute :: paper @@ -274,19 +282,23 @@ class PluginData(object): bool, Indicates whether the plugin uses styles or not, default=True Attribute for DOCGEN, EXPORT plugins + .. attribute :: extension str, The file extension to use for output produced by the docgen/export, default='' Attributes for QUICKREPORT plugins + .. attribute:: runfunc The function that executes the quick report Attributes for MAPSERVICE plugins + .. attribute:: mapservice The class in the module that is a mapservice Attributes for EXPORT plugins + .. attribute:: export_function Function that produces the export .. attribute:: export_options @@ -295,10 +307,12 @@ class PluginData(object): Title for the option page Attributes for IMPORT plugins + .. attribute:: import_function Function that starts an import Attributes for GRAMPLET plugins + .. attribute:: gramplet The function or class that defines the gramplet. .. attribute:: height @@ -318,6 +332,7 @@ class PluginData(object): The URL where documentation for the URL can be found Attributes for VIEW plugins + .. attribute:: viewclass A class of type ViewCreator that holds the needed info of the view to be created: icon, viewclass that derives from pageview, ... @@ -325,12 +340,14 @@ class PluginData(object): The icon in the toolbar or sidebar used to select the view Attributes for SIDEBAR plugins + .. attribute:: sidebarclass The class that defines the sidebar. .. attribute:: menu_label A label to use on the seltion menu. Attributes for VIEW and SIDEBAR plugins + .. attribute:: order order can be START or END. Default is END. For END, on registering, the plugin is appended to the list of plugins. If START, then the @@ -943,7 +960,8 @@ def newplugin(): """ Function to create a new plugindata object, add it to list of registered plugins - :Returns: a newly created PluginData which is already part of the register + + :returns: a newly created PluginData which is already part of the register """ gpr = PluginRegister.get_instance() pgd = PluginData() @@ -956,12 +974,12 @@ def register(ptype, **kwargs): The register functions will call newplugin() function, and use the dictionary kwargs to assign data to the PluginData newplugin() created, as in: plugindata.key = data + :param ptype: the plugin type, one of REPORT, TOOL, ... :param kwargs: dictionary with keys attributes of the plugin, and data - the value - - :Returns: a newly created PluginData which is already part of the register - and which has kwargs assigned as attributes + the value + :returns: a newly created PluginData which is already part of the register + and which has kwargs assigned as attributes """ plg = newplugin() plg.ptype = ptype @@ -1033,9 +1051,11 @@ def make_environment(**kwargs): # #------------------------------------------------------------------------- class PluginRegister(object): - """ PluginRegister is a Singleton which holds plugin data - .. attribute : stable_only - Bool, include stable plugins only or not. Default True + """ + PluginRegister is a Singleton which holds plugin data + + .. attribute : stable_only + Bool, include stable plugins only or not. Default True """ __instance = None @@ -1063,9 +1083,9 @@ class PluginRegister(object): def scan_dir(self, dir): """ The dir name will be scanned for plugin registration code, which will - be loaded in PluginData objects if they satisfy some checks. + be loaded in :class:`PluginData` objects if they satisfy some checks. - :Returns: A list with PluginData objects + :returns: A list with :class:`PluginData` objects """ # if the directory does not exist, do nothing if not (os.path.isdir(dir) or os.path.islink(dir)): @@ -1167,7 +1187,9 @@ class PluginRegister(object): del self.__plugindata[ind] def get_plugin(self, id): - """Return the PluginData for the plugin with id""" + """ + Return the :class:`PluginData` for the plugin with id + """ matches = [x for x in self.__plugindata if x.id == id] matches.sort(key=lambda x: version(x.version)) if len(matches) > 0: @@ -1175,14 +1197,17 @@ class PluginRegister(object): return None def type_plugins(self, ptype): - """Return a list of PluginData that are of type ptype + """ + Return a list of :class:`PluginData` that are of type ptype """ return [self.get_plugin(id) for id in set([x.id for x in self.__plugindata if x.ptype == ptype])] def report_plugins(self, gui=True): - """Return a list of gui or cli PluginData that are of type REPORT - :param gui: bool, if True then gui plugin, otherwise cli plugin + """ + Return a list of gui or cli :class:`PluginData` that are of type REPORT + + :param gui: bool, if True then gui plugin, otherwise cli plugin """ if gui: return [x for x in self.type_plugins(REPORT) if REPORT_MODE_GUI @@ -1192,7 +1217,8 @@ class PluginRegister(object): in x.report_modes] def tool_plugins(self, gui=True): - """Return a list of PluginData that are of type TOOL + """ + Return a list of :class:`PluginData` that are of type TOOL """ if gui: return [x for x in self.type_plugins(TOOL) if TOOL_MODE_GUI @@ -1203,33 +1229,40 @@ class PluginRegister(object): def bookitem_plugins(self): - """Return a list of REPORT PluginData that are can be used as bookitem + """ + Return a list of REPORT :class:`PluginData` that are can be used as + bookitem """ return [x for x in self.type_plugins(REPORT) if REPORT_MODE_BKI in x.report_modes] def quickreport_plugins(self): - """Return a list of PluginData that are of type QUICKREPORT + """ + Return a list of :class:`PluginData` that are of type QUICKREPORT """ return self.type_plugins(QUICKREPORT) def import_plugins(self): - """Return a list of PluginData that are of type IMPORT + """ + Return a list of :class:`PluginData` that are of type IMPORT """ return self.type_plugins(IMPORT) def export_plugins(self): - """Return a list of PluginData that are of type EXPORT + """ + Return a list of :class:`PluginData` that are of type EXPORT """ return self.type_plugins(EXPORT) def docgen_plugins(self): - """Return a list of PluginData that are of type DOCGEN + """ + Return a list of :class:`PluginData` that are of type DOCGEN """ return self.type_plugins(DOCGEN) def general_plugins(self, category=None): - """Return a list of PluginData that are of type GENERAL + """ + Return a list of :class:`PluginData` that are of type GENERAL """ plugins = self.type_plugins(GENERAL) if category: @@ -1238,32 +1271,38 @@ class PluginRegister(object): return plugins def mapservice_plugins(self): - """Return a list of PluginData that are of type MAPSERVICE + """ + Return a list of :class:`PluginData` that are of type MAPSERVICE """ return self.type_plugins(MAPSERVICE) def view_plugins(self): - """Return a list of PluginData that are of type VIEW + """ + Return a list of :class:`PluginData` that are of type VIEW """ return self.type_plugins(VIEW) def relcalc_plugins(self): - """Return a list of PluginData that are of type RELCALC + """ + Return a list of :class:`PluginData` that are of type RELCALC """ return self.type_plugins(RELCALC) def gramplet_plugins(self): - """Return a list of PluginData that are of type GRAMPLET + """ + Return a list of :class:`PluginData` that are of type GRAMPLET """ return self.type_plugins(GRAMPLET) def sidebar_plugins(self): - """Return a list of PluginData that are of type SIDEBAR + """ + Return a list of :class:`PluginData` that are of type SIDEBAR """ return self.type_plugins(SIDEBAR) def filter_load_on_reg(self): - """Return a list of PluginData that have load_on_reg == True + """ + Return a list of :class:`PluginData` that have load_on_reg == True """ return [self.get_plugin(id) for id in set([x.id for x in self.__plugindata diff --git a/gramps/gen/plug/docbackend/docbackend.py b/gramps/gen/plug/docbackend/docbackend.py index c601fe427..3debce49e 100644 --- a/gramps/gen/plug/docbackend/docbackend.py +++ b/gramps/gen/plug/docbackend/docbackend.py @@ -125,7 +125,7 @@ class DocBackend(object): def __init__(self, filename=None): """ - @param filename: path name of the file the backend works on + :param filename: path name of the file the backend works on """ self.__file = None self._filename = filename @@ -139,8 +139,8 @@ class DocBackend(object): def setf(self, value): """ Set the filename on which the backend writes, changing the value - passed on initialization - Can only be done if the previous filename is not open + passed on initialization. + Can only be done if the previous filename is not open. """ if self.__file is not None: raise ValueError(_('Close file first')) @@ -182,40 +182,42 @@ class DocBackend(object): self.__file = None def write(self, string): - """Write a string to the file. There is no return value. - Due to buffering, the string may not actually show up untill the - close() method is called. + """ + Write a string to the file. There is no return value. + Due to buffering, the string may not actually show up until the + :meth:`close` method is called. """ self.__file.write(string) def writelines(self, sequence): - """Write a sequence of strings to the file. The sequence can be any - iterable object producing strings, typically a list of strings. + """ + Write a sequence of strings to the file. The sequence can be any + iterable object producing strings, typically a list of strings. """ self.__file.writelines(sequence) def escape(self, preformatted=False): """ The escape func on text for this file format. - @param preformatted: bool: some formats can have different escape - function for normal text and preformatted text - + + :param preformatted: some formats can have different escape function + for normal text and preformatted text + :type preformatted: bool """ return self.ESCAPE_FUNC() def find_tag_by_stag(self, s_tag): """ - @param s_tag: object: assumed styledtexttag - @param s_tagvalue: None/int/str: value associated with the tag + :param s_tag: object: assumed styledtexttag + :param s_tagvalue: None/int/str: value associated with the tag - A styled tag is type with a value. - Every styled tag must be converted to the tags used in the corresponding - markup for the backend, eg text for bold in html. - These markups are stored in STYLETAG_MARKUP. They are tuples for begin - and end tag - If a markup is not present yet, it is created, using the - _create_xmltag method you can overwrite + A styled tag is type with a value. Every styled tag must be converted + to the tags used in the corresponding markup for the backend, + eg text for bold in html. These markups are stored in + STYLETAG_MARKUP. They are tuples for begin and end tag. If a markup is + not present yet, it is created, using the :meth:`_create_xmltag` method + you can overwrite. """ tagtype = s_tag.name @@ -269,23 +271,23 @@ class DocBackend(object): s_tags which are assumed to be styledtexttags. When split is given the text will be split over the value given, and tags applied in such a way that it the text can be safely splitted in - pieces along split + pieces along split. - @param text : str, a piece of text - @param s_tags : styledtexttags that must be applied to the text - @param split : str, optional. A string along which the output can - be safely split without breaking the styling. + :param text: str, a piece of text + :param s_tags: styledtexttags that must be applied to the text + :param split: str, optional. A string along which the output can + be safely split without breaking the styling. + As adding markup means original text must be escaped, ESCAPE_FUNC is - used - This can be used to convert the text of a styledtext to the format - needed for a document backend - Do not call this method in a report, use the write_markup method + used. This can be used to convert the text of a styledtext to the format + needed for a document backend. Do not call this method in a report, + use the :meth:`write_markup` method. - @note: the algorithm is complex as it assumes mixing of tags is not - allowed: eg text here not is assumed invalid - as markup. If the s_tags require such a setup, what is returned - is text here not - overwrite this method if this complexity is not needed. + .. note:: the algorithm is complex as it assumes mixing of tags is not + allowed: eg text here not is assumed invalid + as markup. If the s_tags require such a setup, what is + returned is text here not + overwrite this method if this complexity is not needed. """ #unicode text must be sliced correctly text = cuni(text) diff --git a/gramps/gen/plug/docgen/basedoc.py b/gramps/gen/plug/docgen/basedoc.py index 341650405..40aac8800 100644 --- a/gramps/gen/plug/docgen/basedoc.py +++ b/gramps/gen/plug/docgen/basedoc.py @@ -67,10 +67,10 @@ class BaseDoc(object): interface. This class should never be instantiated directly, but only through a derived class. - @param styles: StyleSheet containing the styles used. - @param paper_style: PaperStyle instance containing information about - the paper. If set to None, then the document is not a page - oriented document (e.g. HTML) + :param styles: :class:`.StyleSheet` containing the styles used. + :param paper_style: :class:`.PaperStyle` instance containing information + about the paper. If set to None, then the document + is not a page oriented document (e.g. HTML) """ self.paper = paper_style self._style_sheet = styles @@ -90,16 +90,16 @@ class BaseDoc(object): def get_style_sheet(self): """ - Return the StyleSheet of the document. + Return the :class:`.StyleSheet` of the document. """ return StyleSheet(self._style_sheet) def set_style_sheet(self, style_sheet): """ - Set the StyleSheet of the document. + Set the :class:`.StyleSheet` of the document. - @param style_sheet: The new style sheet for the document - @type style_sheet: StyleSheet + :param style_sheet: The new style sheet for the document + :type style_sheet: :class:`.StyleSheet` """ self._style_sheet = StyleSheet(style_sheet) @@ -107,7 +107,7 @@ class BaseDoc(object): """ Opens the file so that it can be generated. - @param filename: path name of the file to create + :param filename: path name of the file to create """ raise NotImplementedError diff --git a/gramps/gen/plug/docgen/drawdoc.py b/gramps/gen/plug/docgen/drawdoc.py index b8af4304e..fb1d9b706 100644 --- a/gramps/gen/plug/docgen/drawdoc.py +++ b/gramps/gen/plug/docgen/drawdoc.py @@ -97,19 +97,27 @@ class DrawDoc(object): raise NotImplementedError def draw_box(self, style, text, x, y, w, h, mark=None): - """ @param mark: IndexMark to use for indexing (if supported) """ + """ + :param mark: :class:`.IndexMark` to use for indexing (if supported) + """ raise NotImplementedError def draw_text(self, style, text, x1, y1, mark=None): - """ @param mark: IndexMark to use for indexing (if supported) """ + """ + :param mark: :class:`.IndexMark` to use for indexing (if supported) + """ raise NotImplementedError def center_text(self, style, text, x1, y1, mark=None): - """ @param mark: IndexMark to use for indexing (if supported) """ + """ + :param mark: :class:`.IndexMark` to use for indexing (if supported) + """ raise NotImplementedError def rotate_text(self, style, text, x, y, angle, mark=None): - """ @param mark: IndexMark to use for indexing (if supported) """ + """ + :param mark: :class:`.IndexMark` to use for indexing (if supported) + """ raise NotImplementedError def draw_line(self, style, x1, y1, x2, y2): diff --git a/gramps/gen/plug/docgen/fontstyle.py b/gramps/gen/plug/docgen/fontstyle.py index f13acbeaf..c4101db07 100644 --- a/gramps/gen/plug/docgen/fontstyle.py +++ b/gramps/gen/plug/docgen/fontstyle.py @@ -76,8 +76,8 @@ class FontStyle(object): """ Create a new FontStyle object, accepting the default values. - @param style: if specified, initializes the FontStyle from the passed - FontStyle instead of using the defaults. + :param style: if specified, initializes the FontStyle from the passed + FontStyle instead of using the defaults. """ if style: self.face = style.face @@ -99,14 +99,14 @@ class FontStyle(object): """ Set font characteristics. - @param face: font type face, either FONT_SERIF or FONT_SANS_SERIF - @param size: type face size in points - @param italic: True enables italics, False disables italics - @param bold: True enables bold face, False disables bold face - @param underline: True enables underline, False disables underline - @param color: an RGB color representation in the form of three integers - in the range of 0-255 represeting the red, green, and blue - components of a color. + :param face: font type face, either FONT_SERIF or FONT_SANS_SERIF + :param size: type face size in points + :param italic: True enables italics, False disables italics + :param bold: True enables bold face, False disables bold face + :param underline: True enables underline, False disables underline + :param color: an RGB color representation in the form of three integers + in the range of 0-255 represeting the red, green, and blue + components of a color. """ if face is not None: self.set_type_face(face) diff --git a/gramps/gen/plug/docgen/graphdoc.py b/gramps/gen/plug/docgen/graphdoc.py index 0292dedd7..c81255647 100644 --- a/gramps/gen/plug/docgen/graphdoc.py +++ b/gramps/gen/plug/docgen/graphdoc.py @@ -130,9 +130,9 @@ class GVOptions(): """ Add all graph related options to the menu. - @param menu: The menu the options should be added to. - @type menu: gen.plug.menu.Menu() - @return: nothing + :param menu: The menu the options should be added to. + :type menu: :class:`.Menu` + :return: nothing """ ################################ category = _("GraphViz Layout") @@ -297,28 +297,28 @@ class GVDoc(object): Add a node to this graph. Nodes can be different shapes like boxes and circles. - @param node_id: A unique identification value for this node. + :param node_id: A unique identification value for this node. Example: "p55" - @type node_id: string - @param label: The text to be displayed in the node. + :type node_id: string + :param label: The text to be displayed in the node. Example: "John Smith" - @type label: string - @param shape: The shape for the node. + :type label: string + :param shape: The shape for the node. Examples: "box", "ellipse", "circle" - @type shape: string - @param color: The color of the node line. + :type shape: string + :param color: The color of the node line. Examples: "blue", "lightyellow" - @type color: string - @param style: The style of the node. - @type style: string - @param fillcolor: The fill color for the node. + :type color: string + :param style: The style of the node. + :type style: string + :param fillcolor: The fill color for the node. Examples: "blue", "lightyellow" - @type fillcolor: string - @param url: A URL for the node. - @type url: string - @param htmloutput: Whether the label contains HTML. - @type htmloutput: boolean - @return: nothing + :type fillcolor: string + :param url: A URL for the node. + :type url: string + :param htmloutput: Whether the label contains HTML. + :type htmloutput: boolean + :return: nothing """ raise NotImplementedError @@ -326,16 +326,16 @@ class GVDoc(object): """ Add a link between two nodes. - @param id1: The unique identifier of the starting node. + :param id1: The unique identifier of the starting node. Example: "p55" - @type id1: string - @param id2: The unique identifier of the ending node. + :type id1: string + :param id2: The unique identifier of the ending node. Example: "p55" - @type id2: string - @param comment: A text string displayed at the end of the link line. + :type id2: string + :param comment: A text string displayed at the end of the link line. Example: "person C is the son of person A and person B" - @type comment: string - @return: nothing + :type comment: string + :return: nothing """ raise NotImplementedError @@ -343,10 +343,10 @@ class GVDoc(object): """ Add a comment to the source file. - @param comment: A text string to add as a comment. + :param comment: A text string to add as a comment. Example: "Next comes the individuals." - @type comment: string - @return: nothing + :type comment: string + :return: nothing """ raise NotImplementedError @@ -354,10 +354,10 @@ class GVDoc(object): """ Start a subgraph in this graph. - @param id: The unique identifier of the subgraph. + :param id: The unique identifier of the subgraph. Example: "p55" - @type id1: string - @return: nothing + :type id1: string + :return: nothing """ raise NotImplementedError @@ -365,7 +365,7 @@ class GVDoc(object): """ End a subgraph that was previously started in this graph. - @return: nothing + :return: nothing """ raise NotImplementedError diff --git a/gramps/gen/plug/docgen/paperstyle.py b/gramps/gen/plug/docgen/paperstyle.py index 902fa1ff5..a3be6e07f 100644 --- a/gramps/gen/plug/docgen/paperstyle.py +++ b/gramps/gen/plug/docgen/paperstyle.py @@ -67,9 +67,9 @@ class PaperSize(object): """ Create a new paper style with. - @param name: name of the new style - @param height: page height in centimeters - @param width: page width in centimeters + :param name: name of the new style + :param height: page height in centimeters + :param width: page width in centimeters """ self.name = name self.height = height @@ -117,10 +117,10 @@ class PaperStyle(object): """ Create a new paper style. - @param size: size of the new style - @type size: PaperSize - @param orientation: page orientation - @type orientation: PAPER_PORTRAIT or PAPER_LANDSCAPE + :param size: size of the new style + :type size: :class:`.PaperSize` + :param orientation: page orientation + :type orientation: PAPER_PORTRAIT or PAPER_LANDSCAPE """ self.__orientation = orientation @@ -142,8 +142,8 @@ class PaperStyle(object): """ Return the size of the paper. - @returns: object indicating the paper size - @rtype: PaperSize + :returns: object indicating the paper size + :rtype: :class:`.PaperSize` """ return self.__size @@ -152,8 +152,8 @@ class PaperStyle(object): """ Return the orientation of the page. - @returns: PAPER_PORTRIAT or PAPER_LANDSCAPE - @rtype: int + :returns: PAPER_PORTRIAT or PAPER_LANDSCAPE + :rtype: int """ return self.__orientation @@ -180,8 +180,8 @@ class PaperStyle(object): """ Return the right margin. - @returns: Right margin in centimeters - @rtype: float + :returns: Right margin in centimeters + :rtype: float """ return self.__rmargin @@ -190,8 +190,8 @@ class PaperStyle(object): """ Return the left margin. - @returns: Left margin in centimeters - @rtype: float + :returns: Left margin in centimeters + :rtype: float """ return self.__lmargin @@ -200,8 +200,8 @@ class PaperStyle(object): """ Return the top margin. - @returns: Top margin in centimeters - @rtype: float + :returns: Top margin in centimeters + :rtype: float """ return self.__tmargin @@ -210,8 +210,8 @@ class PaperStyle(object): """ Return the bottom margin. - @returns: Bottom margin in centimeters - @rtype: float + :returns: Bottom margin in centimeters + :rtype: float """ return self.__bmargin diff --git a/gramps/gen/plug/docgen/paragraphstyle.py b/gramps/gen/plug/docgen/paragraphstyle.py index e434175e0..ae109c0f4 100644 --- a/gramps/gen/plug/docgen/paragraphstyle.py +++ b/gramps/gen/plug/docgen/paragraphstyle.py @@ -63,15 +63,15 @@ PARA_ALIGN_JUSTIFY = 3 class ParagraphStyle(object): """ Defines the characteristics of a paragraph. The characteristics are: - font (a FontStyle instance), right margin, left margin, first indent, - top margin, bottom margin, alignment, level, top border, bottom border, - right border, left border, padding, and background color. + font (a :class:`.FontStyle` instance), right margin, left margin, + first indent, top margin, bottom margin, alignment, level, top border, + bottom border, right border, left border, padding, and background color. """ def __init__(self, source=None): """ - @param source: if not None, then the ParagraphStyle is created - using the values of the source instead of the default values. + :param source: if not None, then the ParagraphStyle is created using the + values of the source instead of the default values. """ if source: self.font = FontStyle(source.font) @@ -127,19 +127,19 @@ class ParagraphStyle(object): """ Allows the values of the object to be set. - @param rmargin: right indent in centimeters - @param lmargin: left indent in centimeters - @param first_indent: first line indent in centimeters - @param tmargin: space above paragraph in centimeters - @param bmargin: space below paragraph in centimeters - @param align: alignment type (PARA_ALIGN_LEFT, PARA_ALIGN_RIGHT, PARA_ALIGN_CENTER, or PARA_ALIGN_JUSTIFY) - @param tborder: non zero indicates that a top border should be used - @param bborder: non zero indicates that a bottom border should be used - @param rborder: non zero indicates that a right border should be used - @param lborder: non zero indicates that a left border should be used - @param pad: padding in centimeters - @param bgcolor: background color of the paragraph as an RGB tuple. - @param font: FontStyle instance that defines the font + :param rmargin: right indent in centimeters + :param lmargin: left indent in centimeters + :param first_indent: first line indent in centimeters + :param tmargin: space above paragraph in centimeters + :param bmargin: space below paragraph in centimeters + :param align: alignment type (PARA_ALIGN_LEFT, PARA_ALIGN_RIGHT, PARA_ALIGN_CENTER, or PARA_ALIGN_JUSTIFY) + :param tborder: non zero indicates that a top border should be used + :param bborder: non zero indicates that a bottom border should be used + :param rborder: non zero indicates that a right border should be used + :param lborder: non zero indicates that a left border should be used + :param pad: padding in centimeters + :param bgcolor: background color of the paragraph as an RGB tuple. + :param font: FontStyle instance that defines the font """ if font is not None: self.font = FontStyle(font) @@ -185,19 +185,20 @@ class ParagraphStyle(object): """ Set the font style of the paragraph. - @param font: FontStyle object containing the font definition to use. + :param font: :class:`.FontStyle` object containing the font definition + to use. """ self.font = FontStyle(font) def get_font(self): - "Return the FontStyle of the paragraph" + "Return the :class:`.FontStyle` of the paragraph" return self.font def set_padding(self, val): """ Set the paragraph padding in centimeters - @param val: floating point value indicating the padding in centimeters + :param val: floating point value indicating the padding in centimeters """ self.pad = val @@ -209,8 +210,8 @@ class ParagraphStyle(object): """ Set the presence or absence of top border. - @param val: True indicates a border should be used, False indicates - no border. + :param val: True indicates a border should be used, False indicates + no border. """ self.top_border = val @@ -222,8 +223,8 @@ class ParagraphStyle(object): """ Set the presence or absence of bottom border. - @param val: True indicates a border should be used, False - indicates no border. + :param val: True indicates a border should be used, False + indicates no border. """ self.bottom_border = val @@ -235,8 +236,8 @@ class ParagraphStyle(object): """ Set the presence or absence of left border. - @param val: True indicates a border should be used, False - indicates no border. + :param val: True indicates a border should be used, False + indicates no border. """ self.left_border = val @@ -248,8 +249,8 @@ class ParagraphStyle(object): """ Set the presence or absence of rigth border. - @param val: True indicates a border should be used, False - indicates no border. + :param val: True indicates a border should be used, False + indicates no border. """ self.right_border = val @@ -268,8 +269,8 @@ class ParagraphStyle(object): """ Set the background color of the paragraph. - @param color: tuple representing the RGB components of a color - (0,0,0) to (255,255,255) + :param color: tuple representing the RGB components of a color + (0,0,0) to (255,255,255) """ self.bgcolor = color @@ -277,8 +278,8 @@ class ParagraphStyle(object): """ Set the paragraph alignment. - @param align: PARA_ALIGN_LEFT, PARA_ALIGN_RIGHT, PARA_ALIGN_CENTER, - or PARA_ALIGN_JUSTIFY + :param align: PARA_ALIGN_LEFT, PARA_ALIGN_RIGHT, PARA_ALIGN_CENTER, + or PARA_ALIGN_JUSTIFY """ self.align = align diff --git a/gramps/gen/plug/docgen/stylesheet.py b/gramps/gen/plug/docgen/stylesheet.py index fb11d81d7..a6667e34d 100644 --- a/gramps/gen/plug/docgen/stylesheet.py +++ b/gramps/gen/plug/docgen/stylesheet.py @@ -231,8 +231,8 @@ class StyleSheet(object): """ Create a new empty StyleSheet. - @param obj: if not None, creates the StyleSheet from the values in - obj, instead of creating an empty StyleSheet + :param obj: if not None, creates the StyleSheet from the values in + obj, instead of creating an empty StyleSheet """ self.para_styles = {} self.draw_styles = {} @@ -253,7 +253,7 @@ class StyleSheet(object): """ Set the name of the StyleSheet - @param name: The name to be given to the StyleSheet + :param name: The name to be given to the StyleSheet """ self.name = name @@ -285,16 +285,16 @@ class StyleSheet(object): """ Add a paragraph style to the style sheet. - @param name: The name of the ParagraphStyle - @param style: ParagraphStyle instance to be added. + :param name: The name of the :class:`.ParagraphStyle` + :param style: :class:`.ParagraphStyle` instance to be added. """ self.para_styles[name] = ParagraphStyle(style) def get_paragraph_style(self, name): """ - Return the ParagraphStyle associated with the name + Return the :class:`.ParagraphStyle` associated with the name - @param name: name of the ParagraphStyle that is wanted + :param name: name of the :class:`.ParagraphStyle` that is wanted """ return ParagraphStyle(self.para_styles[name]) @@ -306,16 +306,16 @@ class StyleSheet(object): """ Add a draw style to the style sheet. - @param name: The name of the GraphicsStyle - @param style: GraphicsStyle instance to be added. + :param name: The name of the :class:`.GraphicsStyle` + :param style: :class:`.GraphicsStyle` instance to be added. """ self.draw_styles[name] = GraphicsStyle(style) def get_draw_style(self, name): """ - Return the GraphicsStyle associated with the name + Return the :class:`.GraphicsStyle` associated with the name - @param name: name of the GraphicsStyle that is wanted + :param name: name of the :class:`.GraphicsStyle` that is wanted """ return GraphicsStyle(self.draw_styles[name]) @@ -327,16 +327,16 @@ class StyleSheet(object): """ Add a table style to the style sheet. - @param name: The name of the TableStyle - @param style: TableStyle instance to be added. + :param name: The name of the :class:`.TableStyle` + :param style: :class:`.TableStyle` instance to be added. """ self.table_styles[name] = TableStyle(style) def get_table_style(self, name): """ - Return the TableStyle associated with the name + Return the :class:`.TableStyle` associated with the name - @param name: name of the TableStyle that is wanted + :param name: name of the :class:`.TableStyle` that is wanted """ return TableStyle(self.table_styles[name]) @@ -348,16 +348,16 @@ class StyleSheet(object): """ Add a cell style to the style sheet. - @param name: The name of the TableCellStyle - @param style: TableCellStyle instance to be added. + :param name: The name of the :class:`.TableCellStyle` + :param style: :class:`.TableCellStyle` instance to be added. """ self.cell_styles[name] = TableCellStyle(style) def get_cell_style(self, name): """ - Return the TableCellStyle associated with the name + Return the :class:`.TableCellStyle` associated with the name - @param name: name of the TableCellStyle that is wanted + :param name: name of the :class:`.TableCellStyle` that is wanted """ return TableCellStyle(self.cell_styles[name]) @@ -380,7 +380,7 @@ class SheetParser(handler.ContentHandler): Create a SheetParser class that populates the passed StyleSheetList class. - sheetlist - StyleSheetList instance to be loaded from the file. + sheetlist - :class:`StyleSheetList` instance to be loaded from the file. """ handler.ContentHandler.__init__(self) self.sheetlist = sheetlist diff --git a/gramps/gen/plug/docgen/tablestyle.py b/gramps/gen/plug/docgen/tablestyle.py index 245bb0fcd..c8b83d00e 100644 --- a/gramps/gen/plug/docgen/tablestyle.py +++ b/gramps/gen/plug/docgen/tablestyle.py @@ -61,8 +61,9 @@ class TableStyle(object): Create a new TableStyle object, with the values initialized to empty, with allocating space for up to 100 columns. - @param obj: if not None, then the object created gets is attributes - from the passed object instead of being initialized to empty. + :param obj: if not None, then the object created gets is attributes + from the passed object instead of being initialized to + empty. """ if obj: self.width = obj.width @@ -90,7 +91,7 @@ class TableStyle(object): """ Set the number of columns. - @param columns: number of columns that should be used. + :param columns: number of columns that should be used. """ self.columns = columns @@ -113,8 +114,8 @@ class TableStyle(object): """ Set the width of a specified column to the specified width. - @param index: column being set (index starts at 0) - @param width: percentage of the table width assigned to the column + :param index: column being set (index starts at 0) + :param width: percentage of the table width assigned to the column """ self.colwid[index] = width @@ -123,7 +124,7 @@ class TableStyle(object): Return the column width of the specified column as a percentage of the entire table width. - @param index: column to return (index starts at 0) + :param index: column to return (index starts at 0) """ return self.colwid[index] @@ -141,8 +142,9 @@ class TableCellStyle(object): """ Create a new TableCellStyle instance. - @param obj: if not None, specifies that the values should be - copied from the passed object instead of being initialized to empty. + :param obj: if not None, specifies that the values should be + copied from the passed object instead of being initialized + to empty. """ if obj: self.rborder = obj.rborder @@ -167,7 +169,7 @@ class TableCellStyle(object): """ Defines if a border is used - @param val: if True, a border is used, if False, it is not + :param val: if True, a border is used, if False, it is not """ self.rborder = val self.lborder = val @@ -178,7 +180,7 @@ class TableCellStyle(object): """ Defines if a right border in used - @param val: if True, a right border is used, if False, it is not + :param val: if True, a right border is used, if False, it is not """ self.rborder = val @@ -186,7 +188,7 @@ class TableCellStyle(object): """ Defines if a left border in used - @param val: if True, a left border is used, if False, it is not + :param val: if True, a left border is used, if False, it is not """ self.lborder = val @@ -194,7 +196,7 @@ class TableCellStyle(object): """ Defines if a top border in used - @param val: if True, a top border is used, if False, it is not + :param val: if True, a top border is used, if False, it is not """ self.tborder = val @@ -202,7 +204,7 @@ class TableCellStyle(object): """ Defines if a bottom border in used - @param val: if 1, a bottom border is used, if 0, it is not + :param val: if 1, a bottom border is used, if 0, it is not """ self.bborder = val diff --git a/gramps/gen/plug/docgen/textdoc.py b/gramps/gen/plug/docgen/textdoc.py index 70d19f564..58f62221b 100644 --- a/gramps/gen/plug/docgen/textdoc.py +++ b/gramps/gen/plug/docgen/textdoc.py @@ -117,10 +117,10 @@ class TextDoc(object): """ Starts a new paragraph, using the specified style name. - @param style_name: name of the ParagraphStyle to use for the - paragraph. - @param leader: Leading text for a paragraph. Typically used - for numbering. + :param style_name: name of the :class:`.ParagraphStyle` to use for the + paragraph. + :param leader: Leading text for a paragraph. Typically used + for numbering. """ raise NotImplementedError @@ -134,8 +134,8 @@ class TextDoc(object): """ Starts a new table. - @param name: Unique name of the table. - @param style_name: TableStyle to use for the new table + :param name: Unique name of the table. + :param style_name: :class:`.TableStyle` to use for the new table """ raise NotImplementedError @@ -159,8 +159,8 @@ class TextDoc(object): """ Starts a new table cell, using the paragraph style specified. - @param style_name: TableCellStyle to use for the cell - @param span: number of columns to span + :param style_name: :class:`.TableCellStyle` to use for the cell + :param span: number of columns to span """ raise NotImplementedError @@ -175,9 +175,9 @@ class TextDoc(object): Writes the text in the current paragraph. Should only be used after a start_paragraph and before an end_paragraph. - @param text: text to write. - @param mark: IndexMark to use for indexing (if supported) - @param links: make URLs in the text clickable (if supported) + :param text: text to write. + :param mark: :class:`.IndexMark` to use for indexing (if supported) + :param links: make URLs in the text clickable (if supported) """ raise NotImplementedError @@ -188,10 +188,10 @@ class TextDoc(object): s_tags, then the same happens as with write_text. Backends supporting write_markup will overwrite this method - @param text: text to write. The text is assumed to be _not_ escaped - @param s_tags: assumed to be list of styledtexttags to apply to the - text - @param mark: IndexMark to use for indexing (if supported) + :param text: text to write. The text is assumed to be _not_ escaped + :param s_tags: assumed to be list of styledtexttags to apply to the + text + :param mark: :class:`.IndexMark` to use for indexing (if supported) """ self.write_text(text, mark=mark) @@ -200,9 +200,9 @@ class TextDoc(object): Writes the note's text and take care of paragraphs, depending on the format. - @param text: text to write. - @param format: format to use for writing. True for flowed text, - 1 for preformatted text. + :param text: text to write. + :param format: format to use for writing. True for flowed text, + 1 for preformatted text. """ raise NotImplementedError @@ -210,14 +210,16 @@ class TextDoc(object): contains_html=False, links=False): """ Convenience function to write a styledtext to the cairo doc. - styledtext : assumed a StyledText object to write - format : = 0 : Flowed, = 1 : Preformatted - style_name : name of the style to use for default presentation - contains_html: bool, the backend should not check if html is present. + + :param styledtext: assumed a :class:`.StyledText` object to write + :param format: 0 = Flowed, 1 = Preformatted + :param style_name: name of the style to use for default presentation + :param contains_html: + bool, the backend should not check if html is present. If contains_html=True, then the textdoc is free to handle that in some way. Eg, a textdoc could remove all tags, or could make sure a link is clickable. - links: bool, make URLs in the text clickable (if supported) + :param links: bool, make URLs in the text clickable (if supported) overwrite this method if the backend supports styled notes """ @@ -226,7 +228,7 @@ class TextDoc(object): def write_text_citation(self, text, mark=None, links=None): """ - Method to write text with GRAMPS citation marks. + Method to write text with Gramps citation marks. """ if not text: return @@ -260,21 +262,22 @@ class TextDoc(object): """ Add a photo of the specified width (in centimeters). - @param name: filename of the image to add - @param align: alignment of the image. Valid values are 'left', - 'right', 'center', and 'single' - @param w_cm: width in centimeters - @param h_cm: height in centimeters - @param alt: an alternative text to use. Useful for eg html reports - @param style_name: style to use for captions - @param crop: image cropping parameters + :param name: filename of the image to add + :param align: alignment of the image. Valid values are 'left', + 'right', 'center', and 'single' + :param w_cm: width in centimeters + :param h_cm: height in centimeters + :param alt: an alternative text to use. Useful for eg html reports + :param style_name: style to use for captions + :param crop: image cropping parameters """ raise NotImplementedError def start_link(self, link): """ Start a link section. This defaults to underlining. - @param link: should be an item that makes sense in this + + :param link: should be an item that makes sense in this docgen type, if it implements linking. """ self.start_underline() diff --git a/gramps/gen/plug/menu/_boolean.py b/gramps/gen/plug/menu/_boolean.py index 7ab18272c..fc1e16c78 100644 --- a/gramps/gen/plug/menu/_boolean.py +++ b/gramps/gen/plug/menu/_boolean.py @@ -42,12 +42,12 @@ class BooleanOption(Option): """ def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Exclude living people" - @type label: string - @param value: An initial value for this option. + :type label: string + :param value: An initial value for this option. Example: True - @type value: boolean - @return: nothing + :type value: boolean + :return: nothing """ Option.__init__(self, label, value) diff --git a/gramps/gen/plug/menu/_booleanlist.py b/gramps/gen/plug/menu/_booleanlist.py index aefc9429a..6383e1226 100644 --- a/gramps/gen/plug/menu/_booleanlist.py +++ b/gramps/gen/plug/menu/_booleanlist.py @@ -41,10 +41,10 @@ class BooleanListOption(Option): """ def __init__(self, heading): """ - @param heading: A heading for the entire list of check buttons. + :param heading: A heading for the entire list of check buttons. Example: "Event groups" - @type heading: string - @return: nothing + :type heading: string + :return: nothing """ Option.__init__(self, heading, '') self.__descriptions = [] @@ -53,13 +53,13 @@ class BooleanListOption(Option): """ Add a check button to the list. - @param description: A description for this check button. + :param description: A description for this check button. Example: "Census" - @type description: string - @param value: The default for this check button (True or False). + :type description: string + :param value: The default for this check button (True or False). Example: True - @type value: int - @return: nothing + :type value: int + :return: nothing """ self.__descriptions.append(description) value = self.get_value() @@ -73,7 +73,7 @@ class BooleanListOption(Option): """ Get a list of check button descriptions for this option. - @return: a list of check button descriptions. + :return: a list of check button descriptions. """ return self.__descriptions @@ -81,7 +81,7 @@ class BooleanListOption(Option): """ Get a list of descriptions where the check button is selected. - @return: a list of check button descriptions. + :return: a list of check button descriptions. """ descriptions = self.__descriptions values = self.get_value().split(',') diff --git a/gramps/gen/plug/menu/_color.py b/gramps/gen/plug/menu/_color.py index ae5e2dc59..1bf58a971 100644 --- a/gramps/gen/plug/menu/_color.py +++ b/gramps/gen/plug/menu/_color.py @@ -42,12 +42,12 @@ class ColorOption(Option): """ def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Males" - @type label: string - @param value: An initial value for this option. + :type label: string + :param value: An initial value for this option. Example: "#ff00a0" - @type value: string - @return: nothing + :type value: string + :return: nothing """ Option.__init__(self, label, value) diff --git a/gramps/gen/plug/menu/_destination.py b/gramps/gen/plug/menu/_destination.py index 7e496652d..648c81b7f 100644 --- a/gramps/gen/plug/menu/_destination.py +++ b/gramps/gen/plug/menu/_destination.py @@ -47,17 +47,17 @@ class DestinationOption(StringOption): def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "File Name" - @type label: string - @param value: A default destination for this option. + :type label: string + :param value: A default destination for this option. Example: "/home/username/Desktop/" Example: "/home/username/Desktop/report.pdf" - @type value: string - @param is_directory: Specifies whether the destination is a directory - or a file. - @type value: bool - @return: nothing + :type value: string + :param is_directory: Specifies whether the destination is a directory + or a file. + :type is_directory: bool + :return: nothing """ StringOption.__init__(self, label, value) self.__is_directory = False @@ -65,31 +65,32 @@ class DestinationOption(StringOption): def set_directory_entry(self, is_directory): """ - @param is_directory: Specifies whether the destination is a directory - or a file. - @type value: bool - @return: nothing + :param is_directory: Specifies whether the destination is a directory + or a file. + :type is_directory: bool + :return: nothing """ self.__is_directory = is_directory self.emit('options-changed') - + def get_directory_entry(self): """ - @return: True if the destination is a directory. False if the - destination is a file. + :return: True if the destination is a directory. False if the + destination is a file. + :rtype: bool """ return self.__is_directory def set_extension(self, extension): """ - @param extension: Specifies the extension for the destination file. - @type value: str - @return: nothing + :param extension: Specifies the extension for the destination file. + :type extension: str + :return: nothing """ self.__extension = extension def get_extension(self): """ - @return: The extension for the destination file. + :return: The extension for the destination file. """ return self.__extension diff --git a/gramps/gen/plug/menu/_enumeratedlist.py b/gramps/gen/plug/menu/_enumeratedlist.py index 36262d1f3..1d6d9976b 100644 --- a/gramps/gen/plug/menu/_enumeratedlist.py +++ b/gramps/gen/plug/menu/_enumeratedlist.py @@ -55,13 +55,13 @@ class EnumeratedListOption(Option): def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Paper Size" - @type label: string - @param value: An initial value for this option. + :type label: string + :param value: An initial value for this option. Example: 5 - @type value: int - @return: nothing + :type value: int + :return: nothing """ Option.__init__(self, label, value) self.__items = [] @@ -70,13 +70,13 @@ class EnumeratedListOption(Option): """ Add an item to the list of possible values. - @param value: The value that corresponds to this item. + :param value: The value that corresponds to this item. Example: 5 - @type value: int - @param description: A description of this value. + :type value: int + :param description: A description of this value. Example: "8.5 x 11" - @type description: string - @return: nothing + :type description: string + :return: nothing """ self.__items.append((value, description)) self.emit('options-changed') @@ -85,10 +85,10 @@ class EnumeratedListOption(Option): """ Add a list of items to the list of possible values. - @param items: A list of tuples containing value, description pairs. + :param items: A list of tuples containing value, description pairs. Example: [ (5,"8.5 x 11"), (6,"11 x 17")] - @type items: array - @return: nothing + :type items: array + :return: nothing """ self.__items = items self.emit('options-changed') @@ -97,7 +97,7 @@ class EnumeratedListOption(Option): """ Get all the possible values for this option. - @return: an array of tuples containing (value,description) pairs. + :return: an array of tuples containing (value,description) pairs. """ return self.__items @@ -105,7 +105,7 @@ class EnumeratedListOption(Option): """ Clear all possible values from this option. - @return: nothing. + :return: nothing. """ self.__items = [] self.emit('options-changed') @@ -114,10 +114,10 @@ class EnumeratedListOption(Option): """ Set the value of this option. - @param value: A value for this option. + :param value: A value for this option. Example: True - @type value: The type will depend on the type of option. - @return: nothing + :type value: The type will depend on the type of option. + :return: nothing """ if value in (v for v, d in self.__items): Option.set_value(self, value) diff --git a/gramps/gen/plug/menu/_family.py b/gramps/gen/plug/menu/_family.py index c2f1fcc02..db585a2b4 100644 --- a/gramps/gen/plug/menu/_family.py +++ b/gramps/gen/plug/menu/_family.py @@ -43,12 +43,12 @@ class FamilyOption(StringOption): """ def __init__(self, label): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Center Family" - @type label: string - @param value: A Gramps ID of a family for this option. + :type label: string + :param value: A Gramps ID of a family for this option. Example: "f11" - @type value: string - @return: nothing + :type value: string + :return: nothing """ StringOption.__init__(self, label, "") diff --git a/gramps/gen/plug/menu/_filter.py b/gramps/gen/plug/menu/_filter.py index 93c92fce1..5144a0a64 100644 --- a/gramps/gen/plug/menu/_filter.py +++ b/gramps/gen/plug/menu/_filter.py @@ -43,13 +43,13 @@ class FilterOption(EnumeratedListOption): """ def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Filter" - @type label: string - @param value: A default value for the option. + :type label: string + :param value: A default value for the option. Example: 1 - @type label: int - @return: nothing + :type label: int + :return: nothing """ EnumeratedListOption.__init__(self, label, value) self.__filters = [] @@ -58,9 +58,9 @@ class FilterOption(EnumeratedListOption): """ Set the list of filters available to be chosen from. - @param filter_list: An array of person filters. - @type filter_list: array - @return: nothing + :param filter_list: An array of person filters. + :type filter_list: array + :return: nothing """ curval = self.get_value() items = [(value, filt.get_name()) @@ -76,6 +76,6 @@ class FilterOption(EnumeratedListOption): """ Return the currently selected filter object. - @return: A filter object. + :return: A filter object. """ return self.__filters[self.get_value()] diff --git a/gramps/gen/plug/menu/_media.py b/gramps/gen/plug/menu/_media.py index 3ad9f80d6..f5c746965 100644 --- a/gramps/gen/plug/menu/_media.py +++ b/gramps/gen/plug/menu/_media.py @@ -43,12 +43,12 @@ class MediaOption(StringOption): """ def __init__(self, label): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Image" - @type label: string - @param value: A Gramps ID of a media object for this option. + :type label: string + :param value: A Gramps ID of a media object for this option. Example: "m11" - @type value: string - @return: nothing + :type value: string + :return: nothing """ StringOption.__init__(self, label, "") diff --git a/gramps/gen/plug/menu/_menu.py b/gramps/gen/plug/menu/_menu.py index a97b30ced..b7631e05e 100644 --- a/gramps/gen/plug/menu/_menu.py +++ b/gramps/gen/plug/menu/_menu.py @@ -31,23 +31,23 @@ Abstracted option handling. #------------------------------------------------------------------------- class Menu(object): """ - Introduction - ============ + **Introduction** + A Menu is used to maintain a collection of options that need to be represented to the user in a non-implementation specific way. The options can be described using the various option classes. A menu contains many options and associates them with a unique name and category. - Usage - ===== + **Usage** + Menus are used in the following way. - 1. Create an option object and configure all the attributes of the option. - 2. Add the option to the menu by specifying the option, name and category. - 3. Add as many options as necessary. - 4. When all the options are added, the menu can be stored and passed to - the part of the system that will actually represent the menu to - the user. + 1. Create an option object and configure all the attributes of the option. + 2. Add the option to the menu by specifying the option, name and category. + 3. Add as many options as necessary. + 4. When all the options are added, the menu can be stored and passed to + the part of the system that will actually represent the menu to + the user. """ def __init__(self): # __options holds all the options by their category @@ -59,16 +59,16 @@ class Menu(object): """ Add an option to the menu. - @param category: A label that describes the category that the option + :param category: A label that describes the category that the option belongs to. Example: "Report Options" - @type category: string - @param name: A name that is unique to this option. + :type category: string + :param name: A name that is unique to this option. Example: "generations" - @type name: string - @param option: The option instance to be added to this menu. - @type option: gen.plug.menu.Option - @return: nothing + :type name: string + :param option: The option instance to be added to this menu. + :type option: gen.plug.menu.Option + :return: nothing """ if category not in self.__options: self.__categories.append(category) @@ -79,7 +79,7 @@ class Menu(object): """ Get a list of categories in this menu. - @return: a list of strings + :return: a list of strings """ return self.__categories @@ -87,7 +87,7 @@ class Menu(object): """ Get a list of option names for the specified category. - @return: a list of strings + :return: a list of strings """ names = [] for (name, option) in self.__options[category]: @@ -98,7 +98,7 @@ class Menu(object): """ Get an option with the specified category and name. - @return: an Option instance or None on failure. + :return: an :class:`.Option` instance or None on failure. """ for (oname, option) in self.__options[category]: if oname == name: @@ -109,7 +109,7 @@ class Menu(object): """ Get a list of all the option names in this menu. - @return: a list of strings + :return: a list of strings """ names = [] for category in self.__options: @@ -121,7 +121,7 @@ class Menu(object): """ Get an option with the specified name. - @return: an Option instance or None on failure. + :return: an :class:`.Option` instance or None on failure. """ for category in self.__options: for (oname, option) in self.__options[category]: diff --git a/gramps/gen/plug/menu/_note.py b/gramps/gen/plug/menu/_note.py index e0527b233..4c8b347aa 100644 --- a/gramps/gen/plug/menu/_note.py +++ b/gramps/gen/plug/menu/_note.py @@ -43,12 +43,12 @@ class NoteOption(StringOption): """ def __init__(self, label): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Title Note" - @type label: string - @param value: A Gramps ID of a note for this option. + :type label: string + :param value: A Gramps ID of a note for this option. Example: "n11" - @type value: string - @return: nothing + :type value: string + :return: nothing """ StringOption.__init__(self, label, "") diff --git a/gramps/gen/plug/menu/_number.py b/gramps/gen/plug/menu/_number.py index 83b592c1e..687828dde 100644 --- a/gramps/gen/plug/menu/_number.py +++ b/gramps/gen/plug/menu/_number.py @@ -43,22 +43,22 @@ class NumberOption(Option): """ def __init__(self, label, value, min_val, max_val, step = 1): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Number of generations to include" - @type label: string - @param value: An initial value for this option. + :type label: string + :param value: An initial value for this option. Example: 5 - @type value: int - @param min: The minimum value for this option. + :type value: int + :param min: The minimum value for this option. Example: 1 - @type min: int - @param max: The maximum value for this option. + :type min: int + :param max: The maximum value for this option. Example: 10 - @type value: int - @param step: The step size for this option. + :type value: int + :param step: The step size for this option. Example: 0.01 - @type value: int or float - @return: nothing + :type value: int or float + :return: nothing """ Option.__init__(self, label, value) self.__min = min_val @@ -69,7 +69,7 @@ class NumberOption(Option): """ Get the minimum value for this option. - @return: an int that represents the minimum value for this option. + :return: an int that represents the minimum value for this option. """ return self.__min @@ -77,7 +77,7 @@ class NumberOption(Option): """ Get the maximum value for this option. - @return: an int that represents the maximum value for this option. + :return: an int that represents the maximum value for this option. """ return self.__max @@ -85,6 +85,6 @@ class NumberOption(Option): """ Get the step size for this option. - @return: an int that represents the step size for this option. + :return: an int that represents the step size for this option. """ return self.__step diff --git a/gramps/gen/plug/menu/_option.py b/gramps/gen/plug/menu/_option.py index fbf6cd154..3e548b55b 100644 --- a/gramps/gen/plug/menu/_option.py +++ b/gramps/gen/plug/menu/_option.py @@ -48,13 +48,13 @@ class Option(Callback): def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Exclude living people" - @type label: string - @param value: An initial value for this option. + :type label: string + :param value: An initial value for this option. Example: True - @type value: The type will depend on the type of option. - @return: nothing + :type value: The type will depend on the type of option. + :return: nothing """ Callback.__init__(self) self.__value = value @@ -66,7 +66,7 @@ class Option(Callback): """ Get the friendly label for this option. - @return: string + :return: string """ return self.__label @@ -74,10 +74,10 @@ class Option(Callback): """ Set the friendly label for this option. - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Exclude living people" - @type label: string - @return: nothing + :type label: string + :return: nothing """ self.__label = label @@ -85,7 +85,7 @@ class Option(Callback): """ Get the value of this option. - @return: The option value. + :return: The option value. """ return self.__value @@ -93,10 +93,10 @@ class Option(Callback): """ Set the value of this option. - @param value: A value for this option. + :param value: A value for this option. Example: True - @type value: The type will depend on the type of option. - @return: nothing + :type value: The type will depend on the type of option. + :return: nothing """ self.__value = value self.emit('value-changed') @@ -105,7 +105,7 @@ class Option(Callback): """ Get the help information for this option. - @return: A string that provides additional help beyond the label. + :return: A string that provides additional help beyond the label. """ return self.__help_str @@ -113,11 +113,11 @@ class Option(Callback): """ Set the help information for this option. - @param help: A string that provides additional help beyond the label. + :param help: A string that provides additional help beyond the label. Example: "Whether to include or exclude people who are calculated to be alive at the time of the generation of this report" - @type value: string - @return: nothing + :type value: string + :return: nothing """ self.__help_str = help_text @@ -125,11 +125,11 @@ class Option(Callback): """ Set the availability of this option. - @param avail: An indicator of whether this option is currently - available. True indicates that the option is available. False indicates - that the option is not available. - @type avail: Bool - @return: nothing + :param avail: An indicator of whether this option is currently + available. True indicates that the option is available. + False indicates that the option is not available. + :type avail: Bool + :return: nothing """ if avail != self.__available: self.__available = avail @@ -139,8 +139,8 @@ class Option(Callback): """ Get the availability of this option. - @return: A Bool indicating the availablity of this option. - True indicates that the option is available. - False indicates that the option is not available. + :return: A Bool indicating the availablity of this option. True + indicates that the option is available. False indicates that + the option is not available. """ return self.__available diff --git a/gramps/gen/plug/menu/_person.py b/gramps/gen/plug/menu/_person.py index 676f2cd65..61f9be53f 100644 --- a/gramps/gen/plug/menu/_person.py +++ b/gramps/gen/plug/menu/_person.py @@ -43,12 +43,12 @@ class PersonOption(StringOption): """ def __init__(self, label): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Center Person" - @type label: string - @param value: A Gramps ID of a person for this option. + :type label: string + :param value: A Gramps ID of a person for this option. Example: "p11" - @type value: string - @return: nothing + :type value: string + :return: nothing """ StringOption.__init__(self, label, "") diff --git a/gramps/gen/plug/menu/_personlist.py b/gramps/gen/plug/menu/_personlist.py index 9605d95e9..9ea06ad36 100644 --- a/gramps/gen/plug/menu/_personlist.py +++ b/gramps/gen/plug/menu/_personlist.py @@ -43,12 +43,12 @@ class PersonListOption(Option): """ def __init__(self, label): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "People of interest" - @type label: string - @param value: A set of GIDs as initial values for this option. + :type label: string + :param value: A set of GIDs as initial values for this option. Example: "111 222 333 444" - @type value: string - @return: nothing + :type value: string + :return: nothing """ Option.__init__(self, label, "") diff --git a/gramps/gen/plug/menu/_placelist.py b/gramps/gen/plug/menu/_placelist.py index d3e2dcab4..149f6697c 100644 --- a/gramps/gen/plug/menu/_placelist.py +++ b/gramps/gen/plug/menu/_placelist.py @@ -43,12 +43,12 @@ class PlaceListOption(Option): """ def __init__(self, label): """ - @param label: A label to be applied to this option. + :param label: A label to be applied to this option. Example: "Places" - @type label: string - @param value: A set of GIDs as initial values for this option. + :type label: string + :param value: A set of GIDs as initial values for this option. Example: "111 222 333 444" - @type value: string - @return: nothing + :type value: string + :return: nothing """ Option.__init__(self, label, "") diff --git a/gramps/gen/plug/menu/_string.py b/gramps/gen/plug/menu/_string.py index 84afff0bf..36c2807d2 100644 --- a/gramps/gen/plug/menu/_string.py +++ b/gramps/gen/plug/menu/_string.py @@ -42,12 +42,12 @@ class StringOption(Option): """ def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Page header" - @type label: string - @param value: An initial value for this option. + :type label: string + :param value: An initial value for this option. Example: "Generated by GRAMPS" - @type value: string - @return: nothing + :type value: string + :return: nothing """ Option.__init__(self, label, value) diff --git a/gramps/gen/plug/menu/_style.py b/gramps/gen/plug/menu/_style.py index dff476ca6..e03c39311 100644 --- a/gramps/gen/plug/menu/_style.py +++ b/gramps/gen/plug/menu/_style.py @@ -44,16 +44,16 @@ class StyleOption(EnumeratedListOption): def __init__(self, label, default_style, module_name): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Style" - @type label: string - @param default_style: A docgen StyleSheet instance which provides the + :type label: string + :param default_style: A docgen StyleSheet instance which provides the default styles. - @type default_style: docgen StyleSheet - @param module_name: The name of the module the style sheets belong to. + :type default_style: docgen StyleSheet + :param module_name: The name of the module the style sheets belong to. Example: "web_cal" - @type module_name: string - @return: nothing + :type module_name: string + :return: nothing """ EnumeratedListOption.__init__(self, label, "default") diff --git a/gramps/gen/plug/menu/_surnamecolor.py b/gramps/gen/plug/menu/_surnamecolor.py index 2ae600d4a..60e2b1b76 100644 --- a/gramps/gen/plug/menu/_surnamecolor.py +++ b/gramps/gen/plug/menu/_surnamecolor.py @@ -44,12 +44,12 @@ class SurnameColorOption(Option): """ def __init__(self, label): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Family lines" - @type label: string - @param value: A set of surnames and colours. + :type label: string + :param value: A set of surnames and colours. Example: "surname1 colour1 surname2 colour2" - @type value: string - @return: nothing + :type value: string + :return: nothing """ Option.__init__(self, label, "") diff --git a/gramps/gen/plug/menu/_text.py b/gramps/gen/plug/menu/_text.py index 92163c72c..25766e05c 100644 --- a/gramps/gen/plug/menu/_text.py +++ b/gramps/gen/plug/menu/_text.py @@ -42,12 +42,12 @@ class TextOption(Option): """ def __init__(self, label, value): """ - @param label: A friendly label to be applied to this option. + :param label: A friendly label to be applied to this option. Example: "Page header" - @type label: string - @param value: An initial value for this option. + :type label: string + :param value: An initial value for this option. Example: "Generated by GRAMPS\nCopyright 2007" - @type value: string - @return: nothing + :type value: string + :return: nothing """ Option.__init__(self, label, value) diff --git a/gramps/gen/plug/report/_bibliography.py b/gramps/gen/plug/report/_bibliography.py index da3d7dabe..d1d97eb4f 100644 --- a/gramps/gen/plug/report/_bibliography.py +++ b/gramps/gen/plug/report/_bibliography.py @@ -43,8 +43,8 @@ class Citation(object): """ Provide the handle to the source that this citation is for. - @return: Source Handle - @rtype: handle + :return: Source Handle + :rtype: handle """ return self.__src_handle @@ -52,8 +52,8 @@ class Citation(object): """ Set the handle for the source that this citation is for. - @param handle: Source Handle - @type handle: handle + :param handle: Source Handle + :type handle: handle """ self.__src_handle = handle @@ -61,8 +61,8 @@ class Citation(object): """ List all the references to this citation. - @return: a list of references - @rtype: list of L{gen.lib.srcref} objects + :return: a list of references + :rtype: list of :class:`~.citation.Citation` objects """ return self.__ref_list @@ -71,10 +71,10 @@ class Citation(object): Add a reference to this citation. If a similar reference exists, don't add another one. - @param source_ref: Source Reference - @type source_ref: L{gen.lib.citation} - @return: The key of the added reference among all the references. - @rtype: char + :param source_ref: Source Reference + :type source_ref: :class:`~.citation.Citation` + :return: The key of the added reference among all the references. + :rtype: char """ letter_count = len(string.ascii_lowercase) ref_count = len(self.__ref_list) @@ -120,12 +120,13 @@ class Bibliography(object): ref information you are interested in by passing in the mode. Possible modes include: - MODE_DATE - MODE_PAGE - MODE_CONF - MODE_NOTE - MODE_MEDIA - MODE_ALL + + - MODE_DATE + - MODE_PAGE + - MODE_CONF + - MODE_NOTE + - MODE_MEDIA + - MODE_ALL If you only care about pages, set "mode=MODE_PAGE". If you only care about dates and pages, set "mode=MODE_DATE|MODE_PAGE". @@ -140,20 +141,22 @@ class Bibliography(object): exists, don't add it again. If a similar reference exists, don't add another one. - @param citation: Citation object - @type citation: L{gen.lib.Citation} - @return: A tuple containing the index of the source among all the - sources and the key of the reference among all the references. If - there is no reference information, the second element will be None. - @rtype: (int,char) or (int,None) + :param citation: Citation object + :type citation: :class:`~.citation.Citation` + :return: A tuple containing the index of the source among all the + sources and the key of the reference among all the references. + If there is no reference information, the second element will + be None. + :rtype: (int,char) or (int,None) - N.B. Within this file, the name 'citation' is used both for - gen.lib.Citation, and for _bibliography.Citation. It is not clear how - best to rename the concepts in this file to avoid the clash, so the - names have been retained. In this function, lib_citation is used for - gen.lib.Citation instances, and citation for _bibliography.Citation - instances. Elsewhere in this file, source_ref is used for - gen.lib.Citation instances. + .. note:: + Within this file, the name 'citation' is used both for + gen.lib.Citation, and for _bibliography.Citation. It is not clear + how best to rename the concepts in this file to avoid the clash, + so the names have been retained. In this function, lib_citation + is used for gen.lib.Citation instances, and citation for + _bibliography.Citation instances. Elsewhere in this file, + source_ref is used for gen.lib.Citation instances. """ source_handle = lib_citation.get_reference_handle() cindex = 0 @@ -186,8 +189,8 @@ class Bibliography(object): """ Report the number of citations in this bibliography. - @return: number of citations - @rtype: int + :return: number of citations + :rtype: int """ return len(self.__citation_list) @@ -195,8 +198,8 @@ class Bibliography(object): """ Return a list containing all the citations in this bibliography. - @return: citation list - @rtype: list of L{Citation} objects + :return: citation list + :rtype: list of :class:`Citation` objects """ return self.__citation_list diff --git a/gramps/gen/plug/report/_options.py b/gramps/gen/plug/report/_options.py index f38f50baa..2cc3874ca 100644 --- a/gramps/gen/plug/report/_options.py +++ b/gramps/gen/plug/report/_options.py @@ -89,166 +89,186 @@ class OptionList(_options.OptionList): def set_style_name(self, style_name): """ Set the style name for the OptionList. - @param style_name: name of the style to set. - @type style_name: str + + :param style_name: name of the style to set. + :type style_name: str """ self.style_name = style_name def get_style_name(self): """ Return the style name of the OptionList. - @returns: string representing the style name - @rtype: str + + :returns: string representing the style name + :rtype: str """ return self.style_name def set_paper_metric(self, paper_metric): """ Set the paper metric for the OptionList. - @param paper_metric: whether to use metric. - @type paper_name: boolean + + :param paper_metric: whether to use metric. + :type paper_name: boolean """ self.paper_metric = paper_metric def get_paper_metric(self): """ Return the paper metric of the OptionList. - @returns: returns whether to use metric - @rtype: boolean + + :returns: returns whether to use metric + :rtype: boolean """ return self.paper_metric def set_paper_name(self, paper_name): """ Set the paper name for the OptionList. - @param paper_name: name of the paper to set. - @type paper_name: str + + :param paper_name: name of the paper to set. + :type paper_name: str """ self.paper_name = paper_name def get_paper_name(self): """ Return the paper name of the OptionList. - @returns: returns the paper name - @rtype: str + + :returns: returns the paper name + :rtype: str """ return self.paper_name def set_orientation(self, orientation): """ Set the orientation for the OptionList. - @param orientation: orientation to set. Possible values are - PAPER_LANDSCAPE or PAPER_PORTRAIT - @type orientation: int + + :param orientation: orientation to set. Possible values are + PAPER_LANDSCAPE or PAPER_PORTRAIT + :type orientation: int """ self.orientation = orientation def get_orientation(self): """ Return the orientation for the OptionList. - @returns: returns the selected orientation. Valid values are - PAPER_LANDSCAPE or PAPER_PORTRAIT - @rtype: int + + :returns: returns the selected orientation. Valid values are + PAPER_LANDSCAPE or PAPER_PORTRAIT + :rtype: int """ return self.orientation def set_custom_paper_size(self, paper_size): """ Set the custom paper size for the OptionList. - @param paper_size: paper size to set in cm. - @type paper_size: [float, float] + + :param paper_size: paper size to set in cm. + :type paper_size: [float, float] """ self.custom_paper_size = paper_size def get_custom_paper_size(self): """ Return the custom paper size for the OptionList. - @returns: returns the custom paper size in cm - @rtype: [float, float] + + :returns: returns the custom paper size in cm + :rtype: [float, float] """ return self.custom_paper_size def set_margins(self, margins): """ Set the margins for the OptionList. - @param margins: margins to set. Possible values are floats in cm - @type margins: [float, float, float, float] + + :param margins: margins to set. Possible values are floats in cm + :type margins: [float, float, float, float] """ self.margins = copy.copy(margins) def get_margins(self): """ Return the margins for the OptionList. - @returns margins: returns the margins, floats in cm - @rtype margins: [float, float, float, float] + + :returns margins: returns the margins, floats in cm + :rtype margins: [float, float, float, float] """ return copy.copy(self.margins) def set_margin(self, pos, value): """ Set a margin for the OptionList. - @param pos: Position of margin [left, right, top, bottom] - @param value: floating point in cm - @type pos: int - @type value: float + + :param pos: Position of margin [left, right, top, bottom] + :type pos: int + :param value: floating point in cm + :type value: float """ self.margins[pos] = value def get_margin(self, pos): """ Return a margin for the OptionList. - @param pos: Position of margin [left, right, top, bottom] - @type pos: int - @returns: float cm of margin - @rtype: float + + :param pos: Position of margin [left, right, top, bottom] + :type pos: int + :returns: float cm of margin + :rtype: float """ return self.margins[pos] def set_css_filename(self, css_filename): """ Set the template name for the OptionList. - @param template_name: name of the template to set. - @type template_name: str + + :param template_name: name of the template to set. + :type template_name: str """ self.css_filename = css_filename def get_css_filename(self): """ Return the template name of the OptionList. - @returns: template name - @rtype: str + + :returns: template name + :rtype: str """ return self.css_filename def set_format_name(self, format_name): """ Set the format name for the OptionList. - @param format_name: name of the format to set. - @type format_name: str + + :param format_name: name of the format to set. + :type format_name: str """ self.format_name = format_name def get_format_name(self): """ Return the format name of the OptionList. - @returns: returns the format name - @rtype: str + + :returns: returns the format name + :rtype: str """ return self.format_name def set_output(self, output): """ Set the output for the OptionList. - @param output: name of the output to set. - @type output: str + + :param output: name of the output to set. + :type output: str """ self.output = output def get_output(self): """ Return the output of the OptionList. - @returns: returns the output name - @rtype: str + + :returns: returns the output name + :rtype: str """ return self.output @@ -287,57 +307,63 @@ class OptionListCollection(_options.OptionListCollection): def set_last_paper_metric(self, paper_metric): """ Set the last paper metric used for any report in this collection. - @param paper_metric: whether to use metric. - @type paper_name: boolean + + :param paper_metric: whether to use metric. + :type paper_name: boolean """ self.last_paper_metric = paper_metric def get_last_paper_metric(self): """ Return the last paper metric used for any report in this collection. - @returns: returns whether or not to use metric - @rtype: boolean + + :returns: returns whether or not to use metric + :rtype: boolean """ return self.last_paper_metric def set_last_paper_name(self, paper_name): """ Set the last paper name used for any report in this collection. - @param paper_name: name of the paper to set. - @type paper_name: str + + :param paper_name: name of the paper to set. + :type paper_name: str """ self.last_paper_name = paper_name def get_last_paper_name(self): """ Return the last paper name used for any report in this collection. - @returns: returns the name of the paper - @rtype: str + + :returns: returns the name of the paper + :rtype: str """ return self.last_paper_name def set_last_orientation(self, orientation): """ Set the last orientation used for any report in this collection. - @param orientation: orientation to set. - @type orientation: int + + :param orientation: orientation to set. + :type orientation: int """ self.last_orientation = orientation def get_last_orientation(self): """ - Return the last orientation used for any report in this - collection. - @returns: last orientation used - @rtype: int + Return the last orientation used for any report in this collection. + + :returns: last orientation used + :rtype: int """ return self.last_orientation def set_last_custom_paper_size(self, custom_paper_size): """ Set the last custom paper size used for any report in this collection. - @param custom_paper_size: size to set in cm (width, height) - @type custom_paper_size: [float, float] + + :param custom_paper_size: size to set in cm (width, height) + :type custom_paper_size: [float, float] """ self.last_custom_paper_size = copy.copy(custom_paper_size) @@ -345,16 +371,18 @@ class OptionListCollection(_options.OptionListCollection): """ Return the last custom paper size used for any report in this collection. - @returns: list of last custom paper size used in cm (width, height) - @rtype: [float, float] + + :returns: list of last custom paper size used in cm (width, height) + :rtype: [float, float] """ return copy.copy(self.last_custom_paper_size) def set_last_margins(self, margins): """ Set the last margins used for any report in this collection. - @param margins: margins to set in cm (left, right, top, bottom) - @type margins: [float, float, float, float] + + :param margins: margins to set in cm (left, right, top, bottom) + :type margins: [float, float, float, float] """ self.last_margins = copy.copy(margins) @@ -362,29 +390,31 @@ class OptionListCollection(_options.OptionListCollection): """ Return the last margins used for any report in this collection. - @returns: list of last margins used in cm (left, right, top, bottom) - @rtype: [float, float, float, float] + + :returns: list of last margins used in cm (left, right, top, bottom) + :rtype: [float, float, float, float] """ return copy.copy(self.last_margins) def set_last_margin(self, pos, value): """ Set the last margin used for any report in this collection. - @param pos: pos to set (0-4) (left, right, top, bottom) - @type pos: int - @param value: value to set the margin to in cm - @type value: float + + :param pos: pos to set (0-4) (left, right, top, bottom) + :type pos: int + :param value: value to set the margin to in cm + :type value: float """ self.last_margins[pos] = value def get_last_margin(self, pos): """ - Return the last margins used for any report in this - collection. - @param pos: position in margins list - @type pos: int - @returns: last margin used in pos - @rtype: float + Return the last margins used for any report in this collection. + + :param pos: position in margins list + :type pos: int + :returns: last margin used in pos + :rtype: float """ return self.last_margins[pos] @@ -392,7 +422,7 @@ class OptionListCollection(_options.OptionListCollection): """ Set the last css used for any report in this collection. - css_filename: name of the style to set. + :param css_filename: name of the style to set. """ self.last_css_name = css_filename @@ -406,7 +436,7 @@ class OptionListCollection(_options.OptionListCollection): """ Set the last format used for any report in this collection. - format_name: name of the format to set. + :param format_name: name of the format to set. """ self.last_format_name = format_name @@ -469,7 +499,7 @@ class OptionListCollection(_options.OptionListCollection): def parse(self): """ - Loads the OptionList from the associated file, if it exists. + Loads the :class:`OptionList` from the associated file, if it exists. """ try: if os.path.isfile(self.filename): @@ -771,7 +801,7 @@ class ReportOptions(_options.Options): def __init__(self, name, dbase): """ Initialize the class, performing usual house-keeping tasks. - Subclasses MUST call this in their __init__() method. + Subclasses MUST call this in their :meth:`__init__` method. """ self.name = name self.options_dict = {} @@ -788,31 +818,37 @@ class ReportOptions(_options.Options): This method MUST be overridden by reports that use the user-adjustable paragraph styles. - NOTE: Unique names MUST be used for all style names, otherwise the - styles will collide when making a book with duplicate style - names. A rule of safety is to prepend style name with the - acronym based on report name. The following acronyms are - already taken: - AC- Ancestor Chart - AC2- Ancestor Chart 2 (Wall Chart) - AHN- Ahnentafel Report - AR- Comprehensive Ancestors report - CBT- Custom Book Text - DG- Descendant Graph - DR- Descendant Report - DAR- Detailed Ancestral Report - DDR- Detailed Descendant Report - FGR- Family Group Report - FC- Fan Chart - FTA- FTM Style Ancestral report - FTD- FTM Style Descendant report - IDS- Individual Complete Report - IDX- Alphabetical Index - IVS- Individual Summary Report - PLC- Place Report - SBT- Simple Book Title - TLG- Timeline Graph - TOC- Table Of Contents + .. note:: Unique names MUST be used for all style names, otherwise the + styles will collide when making a book with duplicate style + names. A rule of safety is to prepend style name with the + acronym based on report name. + + The following acronyms are already taken: + + ==== ================================ + Code Report + ==== ================================ + AC Ancestor Chart + AC2 Ancestor Chart 2 (Wall Chart) + AHN Ahnentafel Report + AR Comprehensive Ancestors report + CBT Custom Book Text + DG Descendant Graph + DR Descendant Report + DAR Detailed Ancestral Report + DDR Detailed Descendant Report + FGR Family Group Report + FC Fan Chart + FTA FTM Style Ancestral report + FTD FTM Style Descendant report + IDS Individual Complete Report + IDX Alphabetical Index + IVS Individual Summary Report + PLC Place Report + SBT Simple Book Title + TLG Timeline Graph + TOC Table Of Contents + ==== ================================ """ pass @@ -820,7 +856,7 @@ class ReportOptions(_options.Options): """ Return document instance. - This method MUST NOT be overridden by subclasses. + .. warning:: This method MUST NOT be overridden by subclasses. """ return self.handler.doc @@ -828,7 +864,7 @@ class ReportOptions(_options.Options): """ Set document to a given instance. - This method MUST NOT be overridden by subclasses. + .. warning:: This method MUST NOT be overridden by subclasses. """ self.handler.doc = val @@ -836,7 +872,7 @@ class ReportOptions(_options.Options): """ Return document output destination. - This method MUST NOT be overridden by subclasses. + .. warning:: This method MUST NOT be overridden by subclasses. """ return self.handler.output @@ -844,7 +880,7 @@ class ReportOptions(_options.Options): """ Set output destination to a given string. - This method MUST NOT be overridden by subclasses. + .. warning:: This method MUST NOT be overridden by subclasses. """ self.handler.output = val @@ -856,7 +892,7 @@ class ReportOptions(_options.Options): class MenuReportOptions(MenuOptions, ReportOptions): """ - The MenuReportOptions class implements the ReportOptions + The MenuReportOptions class implements the :class:`ReportOptions` functionality in a generic way so that the user does not need to be concerned with the actual representation of the options. @@ -933,7 +969,7 @@ class DocOptions(MenuOptions): def __init__(self, name): """ Initialize the class, performing usual house-keeping tasks. - Subclasses MUST call this in their __init__() method. + Subclasses MUST call this in their :meth:`__init__` method. """ self.name = name MenuOptions.__init__(self) @@ -959,7 +995,7 @@ class DocOptionListCollection(_options.OptionListCollection): def parse(self): """ - Loads the OptionList from the associated file, if it exists. + Loads the :class:`OptionList` from the associated file, if it exists. """ try: if os.path.isfile(self.filename): diff --git a/gramps/gen/plug/report/endnotes.py b/gramps/gen/plug/report/endnotes.py index 5f797e7a2..f252f1501 100644 --- a/gramps/gen/plug/report/endnotes.py +++ b/gramps/gen/plug/report/endnotes.py @@ -37,8 +37,8 @@ def add_endnote_styles(style_sheet): """ Add paragraph styles to a style sheet to be used for displaying endnotes. - @param style_sheet: Style sheet - @type style_sheet: L{docgen.StyleSheet} + :param style_sheet: Style sheet + :type style_sheet: :class:`.StyleSheet` """ font = FontStyle() font.set(face=FONT_SANS_SERIF, size=14, italic=1) @@ -82,10 +82,10 @@ def cite_source(bibliography, database, obj): """ Cite any sources for the object and add them to the bibliography. - @param bibliography: The bibliography to contain the citations. - @type bibliography: L{Bibliography} - @param obj: An object with source references. - @type obj: L{gen.lib.CitationBase} + :param bibliography: The bibliography to contain the citations. + :type bibliography: :class:`.Bibliography` + :param obj: An object with source references. + :type obj: :class:`~.citationbase.CitationBase` """ txt = "" slist = obj.get_citation_list() @@ -107,22 +107,22 @@ def write_endnotes(bibliography, database, doc, printnotes=False, links=False, """ Write all the entries in the bibliography as endnotes. - If elocale is passed in (a GrampsLocale), then (insofar as possible) - the translated values will be returned instead. + If elocale is passed in (a :class:`.GrampsLocale`), then (insofar as + possible) the translated values will be returned instead. - @param bibliography: The bibliography that contains the citations. - @type bibliography: L{Bibliography} - @param database: The database that the sources come from. - @type database: DbBase - @param doc: The document to write the endnotes into. - @type doc: L{docgen.TextDoc} - @param printnotes: Indicate if the notes attached to a source must be + :param bibliography: The bibliography that contains the citations. + :type bibliography: :class:`.Bibliography` + :param database: The database that the sources come from. + :type database: DbBase + :param doc: The document to write the endnotes into. + :type doc: :class:`~.docgen.TextDoc` + :param printnotes: Indicate if the notes attached to a source must be written too. - @type printnotes: bool - @param links: Indicate if URL links should be makde 'clickable'. - @type links: bool - @param elocale: allow deferred translation of dates and strings - @type elocale: a GrampsLocale instance + :type printnotes: bool + :param links: Indicate if URL links should be makde 'clickable'. + :type links: bool + :param elocale: allow deferred translation of dates and strings + :type elocale: a :class:`.GrampsLocale` instance """ if bibliography.get_citation_count() == 0: return diff --git a/gramps/gen/plug/report/utils.py b/gramps/gen/plug/report/utils.py index 8ff05cf85..98d46f5fa 100644 --- a/gramps/gen/plug/report/utils.py +++ b/gramps/gen/plug/report/utils.py @@ -55,24 +55,24 @@ from ...constfunc import cuni def pt2cm(pt): """ Convert points to centimeters. Fonts are typically specified in points, - but the BaseDoc classes use centimeters. + but the :class:`.BaseDoc` classes use centimeters. - @param pt: points - @type pt: float or int - @returns: equivalent units in centimeters - @rtype: float + :param pt: points + :type pt: float or int + :returns: equivalent units in centimeters + :rtype: float """ return pt/28.3465 def cm2pt(cm): """ Convert centimeters to points. Fonts are typically specified in points, - but the BaseDoc classes use centimeters. + but the :class:`.BaseDoc` classes use centimeters. - @param cm: centimeters - @type cm: float or int - @returns: equivalent units in points - @rtype: float + :param cm: centimeters + :type cm: float or int + :returns: equivalent units in points + :rtype: float """ return cm*28.3465 @@ -80,10 +80,10 @@ def rgb_color(color): """ Convert color value from 0-255 integer range into 0-1 float range. - @param color: list or tuple of integer values for red, green, and blue - @type color: int - @returns: (r, g, b) tuple of floating point color values - @rtype: 3-tuple + :param color: list or tuple of integer values for red, green, and blue + :type color: int + :returns: (r, g, b) tuple of floating point color values + :rtype: 3-tuple """ r = float(color[0])/255.0 g = float(color[1])/255.0 @@ -178,8 +178,8 @@ def get_person_mark(db, person): """ Return a IndexMark that can be used to index a person in a report - @param db: the GRAMPS database instance - @param person: the key is for + :param db: the Gramps database instance + :param person: the key is for """ if not person: return None @@ -215,7 +215,7 @@ def get_address_str(addr): """ Return a string that combines the elements of an address - @param addr: the GRAMPS address instance + :param addr: the Gramps address instance """ str = "" elems = [ addr.get_street(), @@ -244,10 +244,10 @@ def get_person_filters(person, include_single=True): """ Return a list of filters that are relevant for the given person - @param person: the person the filters should apply to. - @type person: L{Person} - @param include_single: include a filter to include the single person - @type person: boolean + :param person: the person the filters should apply to. + :type person: :class:`~.person.Person` + :param include_single: include a filter to include the single person + :type include_single: boolean """ from ...filters import GenericFilter, rules, CustomFilters from ...display.name import displayer as name_displayer