From 55a3c9813f5ad5f9ffb658c477e9a35fb18cbaa9 Mon Sep 17 00:00:00 2001 From: Nick Hall Date: Wed, 13 Nov 2013 01:18:00 +0000 Subject: [PATCH] Improve cli documentation --- gramps/cli/arghandler.py | 81 +++++++++++++++++++++---------------- gramps/cli/argparser.py | 86 +++++++++++++++++++++------------------- gramps/cli/clidbman.py | 25 +++++++----- gramps/cli/grampscli.py | 25 +++++++----- gramps/cli/user.py | 75 ++++++++++++++++++----------------- 5 files changed, 157 insertions(+), 135 deletions(-) diff --git a/gramps/cli/arghandler.py b/gramps/cli/arghandler.py index 490548170..051d141e2 100644 --- a/gramps/cli/arghandler.py +++ b/gramps/cli/arghandler.py @@ -28,7 +28,7 @@ # $Id$ """ -Module responsible for handling the command line arguments for GRAMPS. +Module responsible for handling the command line arguments for Gramps. """ #------------------------------------------------------------------------- @@ -67,24 +67,31 @@ def _split_options(options_str): Split the options for the action. Rules: - * Entries in the list of options are separated by commas without - spaces between entries - * List values must be inclosed in brackets ("[" and "]") - * Entries within a list value are separated by commas - * Text values (as a value or as entries in a list) do not have to be - enclosed in quotes unless they include commas or quotation marks. - * Text containing double quotes must be contained in single quotes - * Text containing single quotes must be contained in double quotes - * Text cannot include both single and double quotes + + * Entries in the list of options are separated by commas without + spaces between entries + * List values must be inclosed in brackets ("[" and "]") + * Entries within a list value are separated by commas + * Text values (as a value or as entries in a list) do not have to be + enclosed in quotes unless they include commas or quotation marks. + * Text containing double quotes must be contained in single quotes + * Text containing single quotes must be contained in double quotes + * Text cannot include both single and double quotes Examples: - * Multiple options specified: - report -p 'name=ancestor_chart,father_disp=["$n born $b"]' - * Using text with commas and quotes: - title="This is some text with ,s and 's" - title='This is some text with ,s and "s' - * Using a list of text - textlist=[row1,row2,"row3 with ' and ,"] + + Multiple options specified:: + + report -p 'name=ancestor_chart,father_disp=["$n born $b"]' + + Using text with commas and quotes:: + + title="This is some text with ,s and 's" + title='This is some text with ,s and "s' + + Using a list of text:: + + textlist=[row1,row2,"row3 with ' and ,"] """ name = "" value = "" @@ -147,7 +154,7 @@ class ArgHandler(object): """ This class is responsible for the non GUI handling of commands. The handler is passed a parser object, sanitizes it, and can execute the - actions requested working on a DbState. + actions requested working on a :class:`.DbState`. """ def __init__(self, dbstate, parser, sessionmanager, @@ -269,8 +276,9 @@ class ArgHandler(object): def __handle_export_option(self, value, family_tree_format): """ - Handle the "-e" or "--export" option. - Note: this can only happen in the CLI version. + Handle the "-e" or "--export" option. + + .. note:: this can only happen in the CLI version. """ if self.gui: return @@ -317,8 +325,8 @@ class ArgHandler(object): """ Attempt to find a database path for the given parameter. - @return: The path to a Gramps DB - or None if a database can not be deduced. + :returns: The path to a Gramps DB or None if a database can not be + deduced. """ # First, check if this is the name of a family tree db_path = self.dbman.get_family_tree_path(db_name_or_path) @@ -341,15 +349,16 @@ class ArgHandler(object): #------------------------------------------------------------------------- def handle_args_gui(self): """ - method to handle the arguments that can be given for a GUI session. - Returns the filename of the family tree that should be opened if - user just passed a famtree or a filename - 1/no options: a family tree can be given, if so, this name is - tested and returned. If a filename, it is imported - in a new db and name of new db returned - 2/an open and/or import option can have been given, if so, this - is handled, and None is returned - + Method to handle the arguments that can be given for a GUI session. + + :returns: the filename of the family tree that should be opened if + user just passed a famtree or a filename. + + 1. no options: a family tree can be given, if so, this name is tested + and returned. If a filename, it is imported in a new db and name of + new db returned + 2. an open and/or import option can have been given, if so, this is + handled, and None is returned """ if self.open_gui: # First check if a Gramps database was provided @@ -387,8 +396,8 @@ class ArgHandler(object): Depending on the given arguments, import or open data, launch session, write files, and/or perform actions. - @param: climan: the manager of a CLI session - @type: CLIManager object + :param: climan: the manager of a CLI session + :type: :class:`.CLIManager` object """ if self.list: @@ -461,8 +470,10 @@ class ArgHandler(object): def __import_action(self): """ - Take action for all given import files. Note: Family trees are - not supported. + Take action for all given import files. + + .. note:: Family trees are not supported. + If a family tree is open, the import happens on top of it. If not open, a new family tree is created, and the import done. If this is CLI, the created tree is deleted at the end (as some action will diff --git a/gramps/cli/argparser.py b/gramps/cli/argparser.py index b6b894bae..cf0102dd3 100644 --- a/gramps/cli/argparser.py +++ b/gramps/cli/argparser.py @@ -28,7 +28,7 @@ # $Id$ """ -Module responsible for handling the command line arguments for GRAMPS. +Module responsible for handling the command line arguments for Gramps. """ #------------------------------------------------------------------------- @@ -133,35 +133,58 @@ class ArgParser(object): """ This class is responsible for parsing the command line arguments (if any) given to gramps, and determining if a GUI or a CLI session must be started. - The valid arguments are: + A filename and/or options may be specified as arguments. - Possible: - 1/ FAMTREE : Just the family tree (name or database dir) - 2/ -O, --open=FAMTREE, Open of a family tree - 3/ -i, --import=FILE, Import a family tree of any format understood - by an importer, optionally provide -f to indicate format - 4/ -e, --export=FILE, export a family tree in required format, - optionally provide -f to indicate format - 5/ -f, --format=FORMAT : format after a -i or -e option - 6/ -a, --action: An action (possible: 'report', 'tool') - 7/ -p, --options=OPTIONS_STRING : specify options - 8/ -u, --force-unlock: A locked database can be unlocked by giving - this argument when opening it - - If the filename (no flags) is specified, the interactive session is - launched using data from filename. - In this mode (filename, no flags), the rest of the arguments is ignored. - This is a mode suitable by default for GUI launchers, mime type handlers, - and the like + The valid options are: + + -O, --open=FAMILY_TREE Open Family Tree + -C, --create=FAMILY_TREE Create on open if new Family Tree + -i, --import=FILENAME Import file + -e, --export=FILENAME Export file + -f, --format=FORMAT Specify Family Tree format + -a, --action=ACTION Specify action + -p, --options=OPTIONS_STRING Specify options + -d, --debug=LOGGER_NAME Enable debug logs + -l List Family Trees + -L List Family Trees in Detail + -t List Family Trees, tab delimited + -u, --force-unlock Force unlock of Family Tree + -s, --show Show config settings + -c, --config=SETTINGS Set config setting(s) and start Gramps + -y, --yes Don't ask to confirm dangerous actions + -q, --quiet Suppress progress indication output + -v, --version Show versions + -h, --help Display the help + --usage Display usage information + + If the filename (no options) is specified, the interactive session is + launched using data from filename. In this mode (filename, no options), the + rest of the arguments are ignored. This is a mode suitable by default for + GUI launchers, mime type handlers, and the like. If no filename or -i option is given, a new interactive session (empty database) is launched, since no data is given anyway. If -O or -i option is given, but no -e or -a options are given, an - interactive session is launched with the FILE (specified with -i). + interactive session is launched with the ``FILENAME`` (specified with -i). If both input (-O or -i) and processing (-e or -a) options are given, - interactive session will not be launched. + interactive session will not be launched. + + When using import ot export options (-i or -e), the -f option may be + specified to indicate the family tree format. + + Possible values for ``ACTION`` are: 'report', 'book' and 'tool'. + + Configuration ``SETTINGS`` may be specified using the -c option. The + settings are of the form config.setting[:value]. If used without a value, + the setting is shown. + + If the -y option is given, the user's acceptance of any CLI prompt is + assumed. (see :meth:`.cli.user.User.prompt`) + + If the -q option is given, extra noise on sys.stderr, such as progress + indicators, is suppressed. """ def __init__(self, args): @@ -198,25 +221,6 @@ class ArgParser(object): Fill in lists with open, exports, imports, and actions options. Any errors are added to self.errors - - Possible: - 1/ Just the family tree (name or database dir) - 2/ -O --open: Open of a family tree - 3/ -i --import: Import a family tree of any format understood by - an importer, optionally provide -f to indicate format - 4/ -e --export: export a family tree in required format, optionally - provide -f to indicate format - 5/ -f --format=FORMAT : format after a -i or -e option - 6/ -a --action: An action (possible: 'report', 'tool') - 7/ -p --options=OPTIONS_STRING : specify options - 8/ -u --force-unlock: A locked database can be unlocked by giving - this argument when opening it - 9/ -s --show : Show config settings - 10/ -c --config=config.setting:value : Set config.setting and start - Gramps without :value, the actual config.setting is shown - 11/ -y --yes: assume user's acceptance of any CLI prompt (see cli.user.User.prompt) - 12/ -q --quiet: suppress extra noise on sys.stderr, such as progress indicators - """ try: # Convert arguments to unicode, otherwise getopt will not work diff --git a/gramps/cli/clidbman.py b/gramps/cli/clidbman.py index f329ceeb7..6ac6a5b2d 100644 --- a/gramps/cli/clidbman.py +++ b/gramps/cli/clidbman.py @@ -134,7 +134,8 @@ class CLIDbManager(object): self._populate_cli() def empty(self, val): - """Callback that does nothing + """ + Callback that does nothing """ pass @@ -228,7 +229,8 @@ class CLIDbManager(object): return summary_list def _populate_cli(self): - """ Get the list of current names in the database dir + """ + Get the list of current names in the database dir """ # make the default directory if it does not exist dbdir = os.path.expanduser(config.get('behavior.database-path')) @@ -270,7 +272,8 @@ class CLIDbManager(object): return None def family_tree_list(self): - """Return a list of name, dirname of the known family trees + """ + Return a list of name, dirname of the known family trees """ lst = [(x[0], x[1]) for x in self.current_names] return lst @@ -327,14 +330,14 @@ class CLIDbManager(object): A new database will only be created if an appropriate importer was found. - @param filename: a fully-qualified path, filename, and - extension to open. + :param filename: a fully-qualified path, filename, and + extension to open. - @param user: a cli.User or gui.User instance for managing user - interaction. + :param user: a :class:`.cli.user.User` or :class:`.gui.user.User` + instance for managing user interaction. - @return: A tuple of (new_path, name) for the new database - or (None, None) if no import was performed. + :returns: A tuple of (new_path, name) for the new database + or (None, None) if no import was performed. """ pmgr = BasePluginManager.get_instance() # check to see if it isn't a filename directly: @@ -388,7 +391,7 @@ class CLIDbManager(object): def is_locked(self, dbpath): """ - returns True if there is a lock file in the dirpath + Returns True if there is a lock file in the dirpath """ if os.path.isfile(os.path.join(dbpath,"lock")): return True @@ -396,7 +399,7 @@ class CLIDbManager(object): def needs_recovery(self, dbpath): """ - returns True if the database in dirpath needs recovery + Returns True if the database in dirpath needs recovery """ if os.path.isfile(os.path.join(dbpath,"need_recover")): return True diff --git a/gramps/cli/grampscli.py b/gramps/cli/grampscli.py index 99b41e7e3..9e9fc9584 100644 --- a/gramps/cli/grampscli.py +++ b/gramps/cli/grampscli.py @@ -23,9 +23,9 @@ """ Provides the startcli function, which the main program calls for CLI -execution of GRAMPS. +execution of Gramps. -Provides also two small base classes: CLIDbLoader, CLIManager +Provides also two small base classes: :class:`CLIDbLoader`, :class:`CLIManager` """ #------------------------------------------------------------------------- @@ -73,8 +73,8 @@ from gramps.gen.recentfiles import recent_files #------------------------------------------------------------------------- class CLIDbLoader(object): """ - Base class for Db loading action inside a dbstate. Only the minimum is - present needed for CLI handling + Base class for Db loading action inside a :class:`.DbState`. Only the + minimum is present needed for CLI handling """ def __init__(self, dbstate): self.dbstate = dbstate @@ -96,9 +96,11 @@ class CLIDbLoader(object): def _dberrordialog(self, msg): """ Show a database error. - @param: msg : an error message - @type: string - @note: Inherit for GUI action + + :param msg: an error message + :type msg : string + + .. note:: Inherit for GUI action """ self._errordialog( '', _("Low level database corruption detected") + '\n' + @@ -208,7 +210,7 @@ class CLIDbLoader(object): class CLIManager(object): """ - Sessionmanager for GRAMPS. This is in effect a reduced viewmanager + Sessionmanager for Gramps. This is in effect a reduced :class:`.ViewManager` instance (see gui/viewmanager), suitable for CLI actions. Aim is to manage a dbstate on which to work (load, unload), and interact with the plugin session @@ -314,9 +316,10 @@ class CLIManager(object): def startcli(errors, argparser): """ - Starts a cli session of GRAMPS. - errors : errors already encountered - argparser : ArgParser instance + Starts a cli session of Gramps. + + :param errors: errors already encountered + :param argparser: :class:`.ArgParser` instance """ if errors: #already errors encountered. Show first one on terminal and exit diff --git a/gramps/cli/user.py b/gramps/cli/user.py index 4aa8e88f1..120bf3209 100644 --- a/gramps/cli/user.py +++ b/gramps/cli/user.py @@ -56,14 +56,14 @@ _SPINNER = ['|', '/', '-', '\\'] class User(user.User): """ This class provides a means to interact with the user via CLI. - It implements the interface in gramps.gen.user.User() + It implements the interface in :class:`.gen.user.User` """ def __init__(self, callback=None, error=None, auto_accept=False, quiet=False): """ Init. - @param error: If given, notify_error delegates to this callback - @type error: function(title, error) + :param error: If given, notify_error delegates to this callback + :type error: function(title, error) """ user.User.__init__(self, callback, error) self.steps = 0; @@ -83,15 +83,15 @@ class User(user.User): """ Start showing a progress indicator to the user. - @param title: the title of the progress meter - @type title: str - @param message: the message associated with the progress meter - @type message: str - @param steps: the total number of steps for the progress meter. - a value of 0 indicates that the ending is unknown and the - meter should just show activity. - @type steps: int - @returns: none + :param title: the title of the progress meter + :type title: str + :param message: the message associated with the progress meter + :type message: str + :param steps: the total number of steps for the progress meter. + a value of 0 indicates that the ending is unknown and the + meter should just show activity. + :type steps: int + :returns: none """ self._fileout.write(message) self.steps = steps @@ -123,18 +123,19 @@ class User(user.User): """ Prompt the user with a message to select an alternative. - @param title: the title of the question, e.g.: "Undo history warning" - @type title: str - @param message: the message, e.g.: "Proceeding with the tool will - erase the undo history. If you think you may want to revert - running this tool, please stop here and make a backup of the DB." - @type question: str - @param accept_label: what to call the positive choice, e.g.: "Proceed" - @type accept_label: str - @param reject_label: what to call the negative choice, e.g.: "Stop" - @type reject_label: str - @returns: the user's answer to the question - @rtype: bool + :param title: the title of the question, e.g.: "Undo history warning" + :type title: str + :param message: the message, e.g.: "Proceeding with the tool will erase + the undo history. If you think you may want to revert + running this tool, please stop here and make a backup + of the DB." + :type question: str + :param accept_label: what to call the positive choice, e.g.: "Proceed" + :type accept_label: str + :param reject_label: what to call the negative choice, e.g.: "Stop" + :type reject_label: str + :returns: the user's answer to the question + :rtype: bool """ accept_label = accept_label.replace("_", "") reject_label = reject_label.replace("_", "") @@ -154,11 +155,11 @@ class User(user.User): """ Warn the user. - @param title: the title of the warning - @type title: str - @param warning: the warning - @type warning: str - @returns: none + :param title: the title of the warning + :type title: str + :param warning: the warning + :type warning: str + :returns: none """ self._fileout.write("%s %s" % (title, warning)) @@ -166,11 +167,11 @@ class User(user.User): """ Notify the user of an error. - @param title: the title of the error - @type title: str - @param error: the error message - @type error: str - @returns: none + :param title: the title of the error + :type title: str + :param error: the error message + :type error: str + :returns: none """ if self.error_function: self.error_function(title, error) @@ -181,9 +182,9 @@ class User(user.User): """ Notify the user of a DB error. - @param error: the error message - @type error: str - @returns: none + :param error: the error message + :type error: str + :returns: none """ self.notify_error( _("Low level database corruption detected"),