Skip to content

Commit

Permalink
Simplify the documentation of jupytext --to (and include 'md:myst')
Browse files Browse the repository at this point in the history
  • Loading branch information
@mwouts
mwouts committed Jul 30, 2020
1 parent 5b72909 commit 3b8f342
Showing 1 changed file with 75 additions and 77 deletions.
152 changes: 75 additions & 77 deletions jupytext/cli.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
from copy import copy
from tempfile import NamedTemporaryFile
from .jupytext import read, reads, write, writes
from .formats import NOTEBOOK_EXTENSIONS, JUPYTEXT_FORMATS
from .formats import JUPYTEXT_FORMATS
from .formats import _VALID_FORMAT_OPTIONS, _BINARY_FORMAT_OPTIONS, check_file_version
from .formats import (
long_form_one_format,
Expand Down Expand Up @@ -78,43 +78,39 @@ def parse_jupytext_args(args=None):
"Notebook is read from stdin when this argument is empty.",
nargs="*",
)
parser.add_argument(
"--from",
dest="input_format",
help="Jupytext format for the input(s). Inferred from the "
"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.",
)
parser.add_argument(
"--from",
dest="input_format",
help="Jupytext format for the input(s). Inferred from the "
"file extension and content when missing.",
)
# Destination format & act on metadata
parser.add_argument(
"--to",
dest="output_format",
help=(
"Destination format: either 'notebook' (extension .ipynb), "
"'markdown' (.md), 'rmarkdown' (.Rmd), 'script', a supported "
"extension, or an explicit extension/format description "
"[[root_folder/][path/][prefix]/][suffix.]ext[:format_name], where "
+ "ext is one of {}, or auto,".format(
", ".join(ext[1:] for ext in NOTEBOOK_EXTENSIONS)
)
+ "format_name is optional, and can be {} for Markdown files, and ".format(
" or ".join(
"The destination format: 'ipynb', 'markdown' or 'script', or a file extension: "
"'md', 'Rmd', 'jl', 'py', 'R', ..., 'auto' (script extension matching the notebook language), "
"or a combination of an extension and a format name, e.g. {} ".format(
", ".join(
set(
fmt.format_name
"md:{}".format(fmt.format_name)
for fmt in JUPYTEXT_FORMATS
if fmt.extension == ".md"
)
)
)
+ "{} for scripts. ".format(
+ " or {}. ".format(
", ".join(
set(
fmt.format_name
"py:{}".format(fmt.format_name)
for fmt in JUPYTEXT_FORMATS
if fmt.extension == ".py"
)
Expand All @@ -123,49 +119,14 @@ def parse_jupytext_args(args=None):
+ "The default format for scripts is the 'light' format, "
"which uses few cell markers (none when possible). "
"Alternatively, a format compatible with many editors is the "
"'percent' format, which uses '# %%%%' as cell markers "
"'percent' format, which uses '# %%%%' as cell markers. "
"The main formats (markdown, light, percent) preserve "
"notebooks and text documents in a roundtrip. Use the "
"--test and and --test-strict commands to test the roundtrip on your files. "
"Read more about the available formats at "
"https://jupytext.readthedocs.io/en/latest/formats.html"
),
)
parser.add_argument(
"--format-options",
"--opt",
action="append",
help="Set format options with e.g. "
"'--opt comment_magics=true' or '--opt notebook_metadata_filter=-kernelspec'.",
)
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",
)
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')",
)
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. "
"""--update-metadata '{"jupytext":{"formats":"ipynb,py:light"}}' """
"See also the --opt and --set-formats options for other ways "
"to operate on the Jupytext metadata.",
)

# Destination file
parser.add_argument(
Expand All @@ -180,31 +141,51 @@ def parse_jupytext_args(args=None):
"--update",
action="store_true",
help="Preserve the output cells when the destination "
"notebook is a .ipynb file that already exists",
"notebook is an .ipynb file that already exists",
)

parser.add_argument(
"--set-formats",
type=str,
help="Turn the notebook or text document to one or more alternative representations "
"with e.g. '--set-formats ipynb,py:light'. "
"The --set-formats option also triggers the creation/update of all paired files",
)

# Action: convert(default)/version/list paired paths/sync/apply/test
action = parser.add_mutually_exclusive_group()
action.add_argument(
"--version",
"-v",
"--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.",
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.",
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.",
action="store_true",
parser.add_argument(
"--format-options",
"--opt",
action="append",
help="Set format options with e.g. "
"'--opt comment_magics=true' or '--opt notebook_metadata_filter=-kernelspec'.",
)
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. "
"""--update-metadata '{"jupytext":{"formats":"ipynb,py:light"}}' """
"See also the --opt and --set-formats options for other ways "
"to operate on the Jupytext metadata.",
)
action.add_argument(
"--warn-only",
Expand All @@ -216,13 +197,13 @@ def parse_jupytext_args(args=None):
action.add_argument(
"--test",
action="store_true",
help="Test that notebook is stable under a round trip conversion, "
help="Test that the notebook is stable under a round trip conversion, "
"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 the notebook is strictly stable under a round trip conversion",
)
parser.add_argument(
"--stop",
Expand Down Expand Up @@ -269,6 +250,16 @@ def parse_jupytext_args(args=None):
)

# Execute the notebook
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')",
)
parser.add_argument(
"--execute",
action="store_true",
Expand All @@ -283,6 +274,13 @@ def parse_jupytext_args(args=None):
help="Quiet mode: do not comment about files being updated or created",
)

action.add_argument(
"--version",
"-v",
action="store_true",
help="Show jupytext's version number and exit",
)

return parser.parse_args(args)


Expand Down Expand Up @@ -328,14 +326,14 @@ def log(text):

if (
(args.test or args.test_strict)
and not args.to
and not args.output_format
and not args.output
and not args.sync
):
raise ValueError("Please provide one of --to, --output or --sync")

if (
not args.to
not args.output_format
and not args.output
and not args.sync
and not args.pipe
Expand All @@ -356,9 +354,9 @@ def log(text):
if args.input_format:
args.input_format = long_form_one_format(args.input_format)

if args.to:
args.to = long_form_one_format(args.to)
set_format_options(args.to, args.format_options)
if args.output_format:
args.output_format = long_form_one_format(args.output_format)
set_format_options(args.output_format, args.format_options)

# Wildcard extension on Windows #202
notebooks = []
Expand Down Expand Up @@ -390,11 +388,11 @@ def jupytext_single_file(nb_file, args, log):

nb_dest = args.output or (
None
if not args.to
if not args.output_format
else (
"-"
if nb_file == "-"
else full_path(base_path(nb_file, args.input_format), args.to)
else full_path(base_path(nb_file, args.input_format), args.output_format)
)
)

Expand Down Expand Up @@ -440,7 +438,7 @@ def jupytext_single_file(nb_file, args, log):
notebook.metadata.setdefault("jupytext", {})["formats"] = default_formats

# Compute actual extension when using script/auto, and update nb_dest if necessary
dest_fmt = args.to
dest_fmt = args.output_format
if dest_fmt and dest_fmt["extension"] == ".auto":
dest_fmt = check_auto_ext(dest_fmt, notebook.metadata, "--to")
if not args.output and nb_file != "-":
Expand Down

0 comments on commit 3b8f342

Please sign in to comment.