From 4f2644f3efbad2872df66c609c0f085245e61559 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 26 Aug 2009 15:01:47 -0600 Subject: [PATCH] Document the calibredb command in the User Manual --- src/calibre/library/cli.py | 77 +++++++++++++++++++++++++----------- src/calibre/manual/custom.py | 49 +++++++++++++++++++++-- 2 files changed, 101 insertions(+), 25 deletions(-) diff --git a/src/calibre/library/cli.py b/src/calibre/library/cli.py index b5e15b4681..0a392c1b8c 100644 --- a/src/calibre/library/cli.py +++ b/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 command_list(args, dbpath): +def list_option_parser(): 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 command_add(args, dbpath): +def add_option_parser(): 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 command_remove(args, dbpath): - parser = get_parser(_( +def remove_option_parser(): + return 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 command_add_format(args, dbpath): - parser = get_parser(_( +def add_format_option_parser(): + return 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): - parser = get_parser(_( +def remove_format_option_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): - parser = get_parser(_( +def set_metadata_option_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 diff --git a/src/calibre/manual/custom.py b/src/calibre/manual/custom.py index d5bb7efcec..958c2ec6a4 100644 --- a/src/calibre/manual/custom.py +++ b/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): - lines = [] +def render_options(cmd, groups, options_header=True, add_program=True): + 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: