Documentation changes in bob bio annotate

bob/bio/base/script/annotate.py

@@ -5,66 +5,49 @@ import json
 import click
 from os.path import dirname, isfile, expanduser
 from bob.extension.scripts.click_helper import (
-    verbosity_option, ConfigCommand, ResourceOption)
+    verbosity_option, ConfigCommand, ResourceOption, log_parameters)
 from bob.io.base import create_directories_safe
 from bob.bio.base.tools.grid import indices
 
 logger = logging.getLogger(__name__)
 
 
-@click.command(entry_point_group='bob.bio.config', cls=ConfigCommand)
+ANNOTATE_EPILOG = '''\b
+Examples:
+
+  $ bob bio annotate -vvv -d <database> -a <annotator> -o /tmp/annotations
+  $ jman submit --array 64 -- bob bio annotate ... --array 64
+'''
+
+
+@click.command(entry_point_group='bob.bio.config', cls=ConfigCommand,
+               epilog=ANNOTATE_EPILOG)
 @click.option('--database', '-d', required=True, cls=ResourceOption,
-              entry_point_group='bob.bio.database')
+              entry_point_group='bob.bio.database',
+              help='''The database that you want to annotate.''')
 @click.option('--annotator', '-a', required=True, cls=ResourceOption,
-              entry_point_group='bob.bio.annotator')
-@click.option('--output-dir', '-o', required=True, cls=ResourceOption)
-@click.option('--force', '-f', is_flag=True, cls=ResourceOption)
-@click.option('--array', type=click.INT, default=1, cls=ResourceOption)
+              entry_point_group='bob.bio.annotator',
+              help='A callable that takes the database and a sample (biofile) '
+              'of the database and returns the annotations in a dictionary.')
+@click.option('--output-dir', '-o', required=True, cls=ResourceOption,
+              help='The directory to save the annotations.')
+@click.option('--force', '-f', is_flag=True, cls=ResourceOption,
+              help='Whether to overwrite existing annotations.')
+@click.option('--array', type=click.INT, default=1, cls=ResourceOption,
+              help='Use this option alongside gridtk to submit this script as '
+              'an array job.')
 @click.option('--database-directories-file', cls=ResourceOption,
-              default=expanduser('~/.bob_bio_databases.txt'))
+              default=expanduser('~/.bob_bio_databases.txt'),
+              help='(Deprecated) To support loading of old databases.')
 @verbosity_option(cls=ResourceOption)
 def annotate(database, annotator, output_dir, force, array,
              database_directories_file, **kwargs):
     """Annotates a database.
+
     The annotations are written in text file (json) format which can be read
     back using :any:`bob.db.base.read_annotation_file` (annotation_type='json')
-
-    \b
-    Parameters
-    ----------
-    database : :any:`bob.bio.database`
-        The database that you want to annotate. Can be a ``bob.bio.database``
-        entry point or a path to a Python file which contains a variable
-        named `database`.
-    annotator : callable
-        A function that takes the database and a sample (biofile) of the
-        database and returns the annotations in a dictionary. Can be a
-        ``bob.bio.annotator`` entry point or a path to a Python file which
-        contains a variable named `annotator`.
-    output_dir : str
-        The directory to save the annotations.
-    force : bool, optional
-        Whether to overwrite existing annotations.
-    array : int, optional
-        Use this option alongside gridtk to submit this script as an array job.
-    verbose : int, optional
-        Increases verbosity (see help for --verbose).
-
-    \b
-    [CONFIG]...            Configuration files. It is possible to pass one or
-                           several Python files (or names of ``bob.bio.config``
-                           entry points) which contain the parameters listed
-                           above as Python variables. The options through the
-                           command-line (see below) will override the values of
-                           configuration files.
     """
-    logger.debug('database: %s', database)
-    logger.debug('annotator: %s', annotator)
-    logger.debug('force: %s', force)
-    logger.debug('output_dir: %s', output_dir)
-    logger.debug('array: %s', array)
-    logger.debug('database_directories_file: %s', database_directories_file)
-    logger.debug('kwargs: %s', kwargs)
+    log_parameters(logger)
 
     # Some databases need their original_directory to be replaced
     database.replace_directories(database_directories_file)