Mercurial Repository: p/roundup/code: roundup/admin.py comparison

comparison roundup/admin.py @ 8095:5aed4911836b

docs: normalize all help strings and make html output look better.

author	John Rouillard <rouilj@ieee.org>
date	Tue, 16 Jul 2024 21:45:10 -0400
parents	586f76eb33e8
children	e579aef218aa

comparison

equal deleted inserted replaced

-:8e310a7b5e09
+:5aed4911836b
 def help_commands_html(self, indent_re=indent_re):
 """ Produce an HTML command list.
 """
 commands = sorted(iter(self.commands.values()),
 key=operator.attrgetter('__name__'))
+print("<table>")
 for command in commands:
 h = _(command.__doc__).split('\n')
 name = command.__name__[3:]
-usage = h[0]
+usage = h[0].replace('<','&lt;').replace('>','&gt;')[7:]
 print("""
 <tr><td valign=top><strong>%(name)s</strong></td>
-<td><tt>%(usage)s</tt><p>
+<td><tt>- %(usage)s</tt>
 <pre>""" % locals())
-indent = indent_re.match(h[3])
+indent = indent_re.match(h[1])
 if indent: indent = len(indent.group(1))  # noqa: E701
-for line in h[3:]:
+for line in h[1:]:
+line = line.replace('<','&lt;').replace('>','&gt;')
 if indent:
 print(line[indent:])
 else:
 print(line)
 print('</pre></td></tr>\n')
+print("</table>")
 def help_all(self):
 print(_("""
 All commands (except help) require a tracker specifier. This is just
 the path to the roundup tracker you're working with. A roundup tracker
 self.db_uncommitted = True
 return 0
 def do_display(self, args):
 ''"""Usage: display designator[,designator]*
 Show the property values for the given node(s).
 A designator is a classname and a nodeid concatenated,
 eg. bug1, user10, ...
 protected = ""
 print(_('%(protected)s%(key)s: %(value)s') % locals())
 def do_export(self, args, export_files=True):
 ''"""Usage: export [[-]class[,class]] export_dir
-Export the database to colon-separated-value files.
+Export the database and file content.
+Database content is exported to colon separated files.
 To exclude the files (e.g. for the msg or file class),
 use the exporttables command.
 Optionally limit the export to just the named classes
-or exclude the named classes, if the 1st argument starts with '-'.
+or exclude the named classes, if the 1st argument
+starts with '-'.
 This action exports the current data from the database into
 colon-separated-value files that are placed in the nominated
-destination directory.
+export_dir directory.
 """
 # grab the directory to export to
 if len(args) < 1:
 raise UsageError(_('Not enough arguments supplied'))
 max_len, file=sys.stderr)
 return 0
 def do_exporttables(self, args):
 ''"""Usage: exporttables [[-]class[,class]] export_dir
-Export the database to colon-separated-value files, excluding the
+Export only the database to files, no file content.
-files below $TRACKER_HOME/db/files/ (which can be archived separately).
+Database content is exported to colon separated files.
+The files below $TRACKER_HOME/db/files/ (which can be
+archived separately) are not part of the export.
 To include the files, use the export command.
 Optionally limit the export to just the named classes
-or exclude the named classes, if the 1st argument starts with '-'.
+or exclude the named classes, if the 1st argument
+starts with '-'.
 This action exports the current data from the database into
-colon-separated-value files that are placed in the nominated
+colon-separated-value files that are placed in the export_dir
 destination directory.
 """
 return self.do_export(args, export_files=False)
 def do_filter(self, args):
 except (ValueError, TypeError) as message:
 raise UsageError(message)
 return 0
 def do_genconfig(self, args, update=False):
-''"""Usage: genconfig <filename>
+''"""Usage: genconfig filename
-Generate a new tracker config file (ini style) with default
+Create a new tracker config file with default values in filename.
-values in <filename>.
 """
 if len(args) < 1:
 raise UsageError(_('Not enough arguments supplied'))
 if update:
 '"%(nodeid)s"') % locals())
 return 0
 def do_import(self, args, import_files=True):
 ''"""Usage: import import_dir
-Import a database from the directory containing CSV files,
+Import a database and file contents from the directory.
-two per class to import.
+The directory should have the same format as one containing
+the output of export. There are two files imported per class.
 The files used in the import are:
 <class>.csv
 This must define the same properties as the class (including
 having a "header" line with those property names.)
 self.db_uncommitted = True
 return 0
 def do_importtables(self, args):
 ''"""Usage: importtables export_dir
 This imports the database tables exported using exporttables.
+It does not import the content of files like msgs and files.
 """
 return self.do_import(args, import_files=False)
 def do_initialise(self, tracker_home, args):
 ''"""Usage: initialise [adminpw]
 '"%(propname)s"') % locals())
 return 0
 def do_migrate(self, args):  # noqa: ARG002  - args unused
 ''"""Usage: migrate
 Update a tracker's database to be compatible with the Roundup
 codebase.
 You should run the "migrate" command for your tracker once
 you've installed the latest codebase.
 self.db.database_schema['version'])
 return 0
 def do_pack(self, args):
 ''"""Usage: pack period | date
+Remove journal entries older than the date/period.
-Remove journal entries older than a period of time specified or
-before a certain date.
 A period is specified using the suffixes "y", "m", and "d". The
 suffix "w" (for "week") means 7 days.
 "3y" means three years
 self.db_uncommitted = True
 return 0
 def do_perftest(self, args):
 ''"""Usage: perftest [mode] [arguments]*
+Time operations in Roundup.
-Time operations in Roundup. Supported arguments:
+Supported arguments:
 [password] [rounds=<integer>] [scheme=<scheme>]
 'password' is the default mode.  The tracker's config.ini
 setting for 'password_pbkdf2_default_rounds' is the default
 {"time": toc - tic, "scheme": props['scheme'],
 "rounds": rounds})
 def do_pragma(self, args):
 ''"""Usage: pragma setting=value | 'list'
-Set internal admin settings to a value. E.G.
+Set internal admin settings to a value.
+For example:
 pragma verbose=True
 pragma verbose=yes
 pragma verbose=on
 pragma verbose=1
 self.db_uncommitted = False
 return 0
 def do_security(self, args):
 ''"""Usage: security [Role name]
+Display the Permissions available to one or all Roles.
-Display the Permissions available to one or all Roles.
 Also validates that any properties defined in a
 permission are valid.
 Run this after changing your permissions to catch
 typos.
 """
 if len(args) == 1:
 role = args[0]
 try:
 roles = [(args[0].lower(),
 Desc: %(description)s
 """ % templates[name])
 def do_updateconfig(self, args):
 ''"""Usage: updateconfig <filename>
-Generate an updated tracker config file (ini style) in
+Merge existing tracker config with new settings.
-<filename>. Use current settings from existing roundup
-tracker in tracker home.
+Output the updated config file to <filename>. Use current
+settings from existing roundup tracker in tracker home.
 """
 self.do_genconfig(args, update=True)
 def usageError_feedback(self, message, function):
 print(_('Error: %s') % message)

Mercurial > p > roundup > code

comparison roundup/admin.py @ 8095:5aed4911836b