Skip to content

Commit

Permalink
Improve help formatting and show default values
Browse files Browse the repository at this point in the history
  • Loading branch information
@mwouts
mwouts committed Oct 20, 2019
1 parent a29e91d commit b845109
Showing 1 changed file with 74 additions and 45 deletions.
119 changes: 74 additions & 45 deletions jupytext/cli.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,102 +49,130 @@ def str2bool(value):

def parse_jupytext_args(args=None):
"""Command line parser for jupytext"""

class RawTextArgumentDefaultsHelpFormatter(argparse.RawTextHelpFormatter,
argparse.ArgumentDefaultsHelpFormatter):
pass

parser = argparse.ArgumentParser(
description='Jupyter notebooks as markdown documents, Julia, Python or R scripts',
formatter_class=argparse.RawTextHelpFormatter)
formatter_class=RawTextArgumentDefaultsHelpFormatter)

# Input
parser.add_argument('notebooks',
help='One or more notebook(s). Notebook is read from stdin when this argument is empty',
help='One or more notebook(s).\n'
'Notebook is read from stdin when this argument\n'
'is empty.',
nargs='*')
parser.add_argument('--from',
dest='input_format',
help='Optional: jupytext format for the input(s). '
'Inferred from the file extension and content when missing.')
help='Jupytext format for the input(s). Inferred from the\n'
'file extension and content when missing.')
parser.add_argument('--pre-commit',
action='store_true',
help='Ignore the notebook argument, and instead apply Jupytext on the notebooks found '
'in the git index, which have an extension that matches the (optional) --from argument.')
help='Ignore the notebook argument, and instead apply Jupytext\n'
'on the notebooks found in the git index, which have an\n'
'extension that matches the (optional) --from argument.\n')
# Destination format & act on metadata
parser.add_argument('--to',
help="Destination format: either one of 'notebook', 'markdown', 'rmarkdown', 'script', any "
"valid notebook extension, or a full format '[prefix_path//][suffix.]ext[:format_name]")
help="Destination format: either one of 'notebook', 'markdown',\n"
"'rmarkdown', 'script', any valid notebook extension, or a\n"
"full format description, i.e.\n"
"'[prefix_path//][suffix.]ext[:format_name]")
parser.add_argument('--format-options', '--opt',
action='append',
help='Set format options with e.g. --opt comment_magics=true '
'--opt notebook_metadata_filter=-kernelspec.')
help='Set format options with e.g.\n'
' --opt comment_magics=true\n'
' --opt notebook_metadata_filter=-kernelspec.\n')
parser.add_argument('--set-formats',
type=str,
help='Set jupytext.formats metadata to the given value. Use this to activate pairing on a '
'notebook, with e.g. --set-formats ipynb,py:light. The --set-formats option also triggers '
'the creation/update of all paired files')
help='Set jupytext.formats metadata to the given value. Use this to\n'
'activate pairing on a notebook, with e.g.\n'
' --set-formats ipynb,py:light.\n'
'The --set-formats option also triggers the creation/update\n'
'of all paired files')
parser.add_argument('--set-kernel', '-k',
type=str,
help="Set the kernel with the given name on the notebook. Use '--set-kernel -' to set "
"a kernel matching the current environment on Python notebooks, and matching the "
"notebook language otherwise "
"(get the list of available kernels with 'jupyter kernelspec list')")
help="Set the kernel with the given name on the notebook.\n"
"Use\n"
" --set-kernel -\n"
"to set a kernel matching the current\n"
"environment on Python notebooks, and matching the notebook\n"
"language otherwise (get the list of available kernels with\n"
"'jupyter kernelspec list')")
parser.add_argument('--update-metadata',
default={},
type=json.loads,
help='Update the notebook metadata with the desired dictionary. Argument must be given in JSON '
'format. For instance, if you want to activate a pairing in the generated file, '
"""use e.g. '{"jupytext":{"formats":"ipynb,py:light"}}'""")
help='Update the notebook metadata with the desired dictionary.\n'
'Argument must be given in JSON format. For instance, if you\n'
'want to activate a pairing in the generated file, use e.g.\n'
""" --update-metadata '{"jupytext":{"formats":"ipynb,py:light"}}'\n"""
"See also the '--opt' and '--set-formats' options for other ways\n"
"to operate on the Jupytext metadata."
)

# Destination file
parser.add_argument('-o', '--output',
help="Destination file. Defaults to the original file, with prefix/suffix/extension changed"
"according to the destination format. Use '-' to print the notebook on stdout.")
help="Destination file. Defaults to the original file,\n"
"with prefix/suffix/extension changed according to\n"
"the destination format.\n"
"Use '-' to print the notebook on stdout.")
parser.add_argument('--update', action='store_true',
help='Preserve the output cells when the destination notebook is a .ipynb file '
'that already exists')
help='Preserve the output cells when the destination\n'
'notebook is a .ipynb file that already exists')

# Action: convert(default)/version/list paired paths/sync/apply/test
action = parser.add_mutually_exclusive_group()
action.add_argument('--version', '-v',
action='store_true',
help="Show jupytext's version number and exit")
action.add_argument('--paired-paths', '-p',
help='List the locations of the alternative representations for this notebook.',
help='List the locations of the alternative representations\n'
'for this notebook.',
action='store_true')
action.add_argument('--sync', '-s',
help='Synchronize the content of the paired representations of the given notebook. '
'Input cells are taken from the file that was last modified, and outputs are read '
'from the ipynb file, if present.',
help='Synchronize the content of the paired representations of\n'
'the given notebook. Input cells are taken from the file that\n'
'was last modified, and outputs are read from the ipynb file,\n'
'if present.',
action='store_true')
action.add_argument('--warn-only', '-w',
action='store_true',
help='Only issue a warning and continue processing other notebooks when the conversion of a '
'given notebook fails')
help='Only issue a warning and continue processing other notebooks\n'
'when the conversion of a given notebook fails')
action.add_argument('--test',
action='store_true',
help='Test that notebook is stable under a round trip conversion, up to the expected changes')
help='Test that notebook is stable under a round trip conversion,\n'
'up to the expected changes')
action.add_argument('--test-strict',
action='store_true',
help='Test that notebook is strictly stable under a round trip conversion')
help='Test that notebook is strictly stable under a round trip\n'
'conversion')
parser.add_argument('--stop', '-x',
dest='stop_on_first_error',
action='store_true',
help='In --test mode, stop on first round trip conversion error, and report stack traceback')
help='In --test mode, stop on first round trip conversion error, and report\n'
'stack traceback')

# Pipe notebook inputs into other commands
parser.add_argument('--pipe',
action='append',
help='Pipe the text representation of the notebook into another program, and read the'
'notebook back. For instance, reformat your notebook with:'
" jupytext notebook.ipynb --pipe black"
'If you want to reformat it and sync the paired representation, execute:'
" jupytext notebook.ipynb --sync --pipe black")
help='Pipe the text representation of the notebook into another\n'
'program, and read the notebook back. For instance, reformat\n'
'your notebook with:\n'
" jupytext notebook.ipynb --pipe black\n"
'If you want to reformat it and sync the paired representation, execute:\n'
" jupytext notebook.ipynb --sync --pipe black\n")
parser.add_argument('--check',
action='append',
help='Pipe the text representation of the notebook into another program, and test that '
'the returned value is non zero. For instance, test that your notebook is pep8 compliant '
'with:'
" jupytext notebook.ipynb --check flake8")
help='Pipe the text representation of the notebook into another program,\n'
'and test that the returned value is non zero. For instance,\n'
'test that your notebook is pep8 compliant with:\n'
" jupytext notebook.ipynb --check flake8\n")
parser.add_argument('--pipe-fmt',
default='auto:percent',
help='The format in which the notebook should be piped to other programs, when using the '
'--pipe and/or --check commands.')
help='The format in which the notebook should be piped to other programs,\n'
'when using the --pipe and/or --check commands.')

# Execute the notebook
parser.add_argument('--execute',
Expand All @@ -154,7 +182,8 @@ def parse_jupytext_args(args=None):
parser.add_argument('--quiet', '-q',
action='store_true',
default=False,
help='Quiet mode: do not comment about files being updated or created')
help='Quiet mode: do not comment about files being updated\n'
'or created')

return parser.parse_args(args)

Expand Down

0 comments on commit b845109

Please sign in to comment.