search

mwouts / jupytext

Jupyter Notebooks as Markdown Documents, Julia, Python or R scripts
https://jupytext.readthedocs.io
MIT License
6.61k stars 385 forks source link

Lacking documentation #433

Open Atcold opened 4 years ago

Atcold commented 4 years ago

I was trying to figure out what "formats" are available from the CMI help jupytext --help. For what I can see there is only one reference to py:light, and nothing else.

How is one made aware of the alternatives?

mwouts commented 4 years ago

Hello @Atcold , thanks for asking. The formats are documented at https://jupytext.readthedocs.io/en/latest/formats.html, but I agree with you, they could also be listed in the CLI help. Let me see how we can do that...

Atcold commented 4 years ago

@mwouts I'm now aware what the formats are. I couldn't figure that out from my terminal, though.

mwouts commented 4 years ago

@Atcold , could you let me know what you think of #441 ? Thanks

allefeld commented 1 month ago

The PR #441 once included a list of all formats in the CLI help, but since then that seems to have been changed, so that again there is no apparent way to get that list. At least with current 1.16.4, jupytext --help prints only a partial list:

  --to OUTPUT_FORMAT    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. md:markdown, md:pandoc, md:myst
                        or py:sphinx, py:nomarker, py:light, py:percent, py:hydrogen. 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. 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 (default:
                        None)

Moreover, the included link is broken.

There is a list of supported languages in the documentation, but it does not include the corresponding values to use for --to.

I admit that to users of a specific language the correct values are probably obvious, but it would still be nice to have complete documentation.

mwouts commented 1 month ago

Thank you @allefeld for the suggestion, I will have a look when time permits!