Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-09 03:04:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Document the calibredb command in the User Manual

Browse Source
This commit is contained in:
Kovid Goyal 2009-08-26 15:01:47 -06:00
parent f289c6b44b
commit 4f2644f3ef
2 changed files with 101 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
src/calibre/library/cli.py
View File

@ -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

49
src/calibre/manual/custom.py
View File

@ -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: