Document the calibredb command in the User Manual

src/calibre/library/cli.py

@@ -183,9 +183,7 @@ def do_list(db, fields, sort_by, ascending, search_text, line_width, separator,
         return template.generate(id="urn:calibre:main", data=data, subtitle=subtitle,
                 sep=os.sep, quote=quote, updated=db.last_modified()).render('xml')
 
-
+def list_option_parser():
-
-def command_list(args, dbpath):
     parser = get_parser(_(
 '''\
 %prog list [options]
@@ -208,6 +206,11 @@ List the books available in the calibre database.
     of = ['text', 'xml', 'stanza']
     parser.add_option('--output-format', choices=of, default='text',
                       help=_('The format in which to output the data. Available choices: %s. Defaults is text.')%of)
+    return parser
+
+
+def command_list(args, dbpath):
+    parser = list_option_parser()
     opts, args = parser.parse_args(sys.argv[:1] + args)
     fields = [str(f.strip().lower()) for f in opts.fields.split(',')]
     if 'all' in fields:
@@ -316,9 +319,7 @@ def do_add(db, paths, one_book_per_directory, recurse, add_duplicates):
     finally:
         sys.stdout = orig
 
-
+def add_option_parser():
-
-def command_add(args, dbpath):
     parser = get_parser(_(
 '''\
 %prog add [options] file1 file2 file3 ...
@@ -333,6 +334,11 @@ the directory related options below.
                       help=_('Process directories recursively'))
     parser.add_option('-d', '--duplicates', action='store_true', default=False,
                       help=_('Add books to database even if they already exist. Comparison is done based on book titles.'))
+    return parser
+
+
+def command_add(args, dbpath):
+    parser = add_option_parser()
     opts, args = parser.parse_args(sys.argv[:1] + args)
     if len(args) < 2:
         parser.print_help()
@@ -353,9 +359,8 @@ def do_remove(db, ids):
     if send_message is not None:
         send_message('refreshdb:', 'calibre GUI')
 
-
+def remove_option_parser():
-def command_remove(args, dbpath):
+    return get_parser(_(
-    parser = get_parser(_(
 '''\
 %prog remove ids
 
@@ -363,6 +368,9 @@ Remove the books identified by ids from the database. ids should be a comma sepa
 list of id numbers (you can get id numbers by using the list command). For example, \
 23,34,57-85
 '''))
+
+def command_remove(args, dbpath):
+    parser = remove_option_parser()
     opts, args = parser.parse_args(sys.argv[:1] + args)
     if len(args) < 2:
         parser.print_help()
@@ -385,15 +393,18 @@ list of id numbers (you can get id numbers by using the list command). For examp
 def do_add_format(db, id, fmt, path):
     db.add_format_with_hooks(id, fmt.upper(), path, index_is_id=True)
 
-
+def add_format_option_parser():
-def command_add_format(args, dbpath):
+    return get_parser(_(
-    parser = get_parser(_(
 '''\
 %prog add_format [options] id ebook_file
 
 Add the ebook in ebook_file to the available formats for the logical book identified \
 by id. You can get id by using the list command. If the format already exists, it is replaced.
 '''))
+
+
+def command_add_format(args, dbpath):
+    parser = add_format_option_parser()
     opts, args = parser.parse_args(sys.argv[:1] + args)
     if len(args) < 3:
         parser.print_help()
@@ -410,8 +421,8 @@ by id. You can get id by using the list command. If the format already exists, i
 def do_remove_format(db, id, fmt):
     db.remove_format(id, fmt, index_is_id=True)
 
-def command_remove_format(args, dbpath):
+def remove_format_option_parser():
-    parser = get_parser(_(
+    return get_parser(_(
 '''
 %prog remove_format [options] id fmt
 
@@ -420,6 +431,10 @@ You can get id by using the list command. fmt should be a file extension \
 like LRF or TXT or EPUB. If the logical book does not have fmt available, \
 do nothing.
 '''))
+
+
+def command_remove_format(args, dbpath):
+    parser = remove_format_option_parser()
     opts, args = parser.parse_args(sys.argv[:1] + args)
     if len(args) < 3:
         parser.print_help()
@@ -441,7 +456,7 @@ def do_show_metadata(db, id, as_opf):
     else:
         print unicode(mi).encode(preferred_encoding)
 
-def command_show_metadata(args, dbpath):
+def show_metadata_option_parser():
     parser = get_parser(_(
 '''
 %prog show_metadata [options] id
@@ -451,6 +466,10 @@ id is an id number from the list command.
 '''))
     parser.add_option('--as-opf', default=False, action='store_true',
                       help=_('Print metadata in OPF form (XML)'))
+    return parser
+
+def command_show_metadata(args, dbpath):
+    parser = show_metadata_option_parser()
     opts, args = parser.parse_args(sys.argv[1:]+args)
     if len(args) < 2:
         parser.print_help()
@@ -468,8 +487,8 @@ def do_set_metadata(db, id, stream):
     if send_message is not None:
         send_message('refreshdb:', 'calibre GUI')
 
-def command_set_metadata(args, dbpath):
+def set_metadata_option_parser():
-    parser = get_parser(_(
+    return get_parser(_(
 '''
 %prog set_metadata [options] id /path/to/metadata.opf
 
@@ -478,6 +497,9 @@ from the OPF file metadata.opf. id is an id number from the list command. You
 can get a quick feel for the OPF format by using the --as-opf switch to the
 show_metadata command.
 '''))
+
+def command_set_metadata(args, dbpath):
+    parser = set_metadata_option_parser()
     opts, args = parser.parse_args(sys.argv[1:]+args)
     if len(args) < 3:
         parser.print_help()
@@ -501,7 +523,7 @@ def do_export(db, ids, dir, opts):
             prints('\t'+'\n\t'.join(tb.splitlines()))
             prints(' ')
 
-def command_export(args, dbpath):
+def export_option_parser():
     parser = get_parser(_('''\
 %prog export [options] ids
 
@@ -536,6 +558,10 @@ an opf file). You can get id numbers from the list command.
         parser.add_option(switch, default=False, action='store_true',
                 help=opt.help)
 
+    return parser
+
+def command_export(args, dbpath):
+    parser = export_option_parser()
     opts, args = parser.parse_args(sys.argv[1:]+args)
     if (len(args) < 2 and not opts.all):
         parser.print_help()
@@ -547,9 +573,11 @@ an opf file). You can get id numbers from the list command.
     do_export(get_db(dbpath, opts), ids, dir, opts)
     return 0
 
-def main(args=sys.argv):
+COMMANDS = ('list', 'add', 'remove', 'add_format', 'remove_format',
-    commands = ('list', 'add', 'remove', 'add_format', 'remove_format',
                 'show_metadata', 'set_metadata', 'export')
+
+
+def option_parser():
     parser = OptionParser(_(
 '''\
 %%prog command [options] [arguments]
@@ -561,11 +589,16 @@ command is one of:
 
 For help on an individual command: %%prog command --help
 '''
-                          )%'\n  '.join(commands))
+                          )%'\n  '.join(COMMANDS))
+    return parser
+
+
+def main(args=sys.argv):
+    parser = option_parser()
     if len(args) < 2:
         parser.print_help()
         return 1
-    if args[1] not in commands:
+    if args[1] not in COMMANDS:
         if args[1] == '--version':
             parser.print_version()
             return 0

src/calibre/manual/custom.py

@@ -69,6 +69,46 @@ CLI_PREAMBLE='''\
 {usage}
 '''
 
+def generate_calibredb_help(preamble, info):
+    from calibre.library.cli import COMMANDS, get_parser
+    import calibre.library.cli as cli
+    preamble = preamble[:preamble.find('\n\n\n', preamble.find('code-block'))]
+    preamble += textwrap.dedent('''
+
+    :command:`calibredb` is the command line interface to the |app| database. It has
+    several sub-commands, documented below:
+
+    ''')
+
+    global_parser = get_parser('')
+    groups = []
+    for grp in global_parser.option_groups:
+        groups.append((grp.title.capitalize(), grp.description, grp.option_list))
+
+    global_options = '\n'.join(render_options('calibredb', groups, False, False))
+
+
+    lines, toc = [], []
+    for cmd in COMMANDS:
+        parser = getattr(cli, cmd+'_option_parser')()
+        toc.append('  * :ref:`calibredb-%s`'%cmd)
+        lines += ['.. _calibredb-'+cmd+':', '']
+        lines += [cmd, '~'*20, '']
+        usage = parser.usage.strip()
+        usage = [i for i in usage.replace('%prog', 'calibredb').splitlines()]
+        cmdline = '    '+usage[0]
+        usage = usage[1:]
+        usage = [i.replace(cmd, ':command:`%s`'%cmd) for i in usage]
+        lines += ['.. code-block:: none', '', cmdline, '']
+        lines += usage
+        groups = [(None, None, parser.option_list)]
+        lines += ['']
+        lines += render_options('calibredb '+cmd, groups, False)
+        lines += ['']
+
+    toc = '\n'.join(toc)
+    raw = preamble + '\n\n'+toc + '\n\n' + global_options+'\n\n'+'\n'.join(lines)
+    update_cli_doc(os.path.join('cli', 'calibredb.rst'), raw, info)
 
 def generate_ebook_convert_help(preamble, info):
     from calibre.ebooks.conversion.cli import create_option_parser
@@ -125,11 +165,12 @@ def update_cli_doc(path, raw, info):
         info('creating '+os.path.splitext(os.path.basename(path))[0])
         open(path, 'wb').write(raw)
 
-def render_options(cmd, groups, options_header=True):
+def render_options(cmd, groups, options_header=True, add_program=True):
-    lines = []
+    lines = ['']
     if options_header:
         lines = ['[options]', '-'*15, '']
-    lines += ['.. program:: '+cmd, '']
+    if add_program:
+        lines += ['.. program:: '+cmd, '']
     for title, desc, options in groups:
         if title:
             lines.extend([title, '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'])
@@ -180,6 +221,8 @@ def cli_docs(app):
         preamble = CLI_PREAMBLE.format(cmd=cmd, cmdline=cmdline, usage=usage)
         if cmd == 'ebook-convert':
             generate_ebook_convert_help(preamble, info)
+        elif cmd == 'calibredb':
+            generate_calibredb_help(preamble, info)
         else:
             groups = [(None, None, parser.option_list)]
             for grp in parser.option_groups: