Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/iliazeus/node-nbconvert

nbconvert utility packaged to distribute via NPM
https://github.com/iliazeus/node-nbconvert

jupyter nbconvert nodejs notebook

Last synced: about 2 months ago
JSON representation

nbconvert utility packaged to distribute via NPM

Host: GitHub
URL: https://github.com/iliazeus/node-nbconvert
Owner: iliazeus
License: mit
Created: 2022-12-23T10:12:57.000Z (about 2 years ago)
Default Branch: master
Last Pushed: 2023-06-30T11:07:49.000Z (over 1 year ago)
Last Synced: 2024-11-07T23:52:56.428Z (about 2 months ago)
Topics: jupyter, nbconvert, nodejs, notebook
Language: JavaScript
Homepage: https://npmjs.org/package/nbconvert
Size: 8.79 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.ipynb
- License: LICENSE

Awesome Lists containing this project

README

{
"cells": [
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"# nbconvert\n",
"\n",
"The [`nbconvert`](https://github.com/jupyter/nbconvert) utility, packaged to be distributed via NPM and used in Node.js package scripts.\n",
"\n",
"This README [is a notebook](https://github.com/iliazeus/node-nbconvert/blob/master/README.ipynb)!\n",
"\n",
"## Why?\n",
"\n",
"Notebooks are a great tool and a de-factor standard for [literate programming](https://en.wikipedia.org/wiki/Literate_programming).\n",
"For example, you can easily create and automatically maintain an up-to-date README file, like this one!\n",
"\n",
"\n",
"\n",
"Example: usage of nbconvert\n",
"\n",
"(you can use the `--no-input` flag to hide input cells like this one)"
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"This application is used to convert notebook files (*.ipynb)\n",
" to various other formats.\n",
"\n",
" WARNING: THE COMMANDLINE INTERFACE MAY CHANGE IN FUTURE RELEASES.\n",
"\n",
"Options\n",
"=======\n",
"The options below are convenience aliases to configurable class-options,\n",
"as listed in the \"Equivalent to\" description-line of the aliases.\n",
"To see all configurable class-options for some , use:\n",
" --help-all\n",
"\n",
"--debug\n",
" set log level to logging.DEBUG (maximize logging output)\n",
" Equivalent to: [--Application.log_level=10]\n",
"--show-config\n",
" Show the application's configuration (human-readable format)\n",
" Equivalent to: [--Application.show_config=True]\n",
"--show-config-json\n",
" Show the application's configuration (json format)\n",
" Equivalent to: [--Application.show_config_json=True]\n",
"--generate-config\n",
" generate default config file\n",
" Equivalent to: [--JupyterApp.generate_config=True]\n",
"-y\n",
" Answer yes to any questions instead of prompting.\n",
" Equivalent to: [--JupyterApp.answer_yes=True]\n",
"--execute\n",
" Execute the notebook prior to export.\n",
" Equivalent to: [--ExecutePreprocessor.enabled=True]\n",
"--allow-errors\n",
" Continue notebook execution even if one of the cells throws an error and include the error message in the cell output (the default behaviour is to abort conversion). This flag is only relevant if '--execute' was specified, too.\n",
" Equivalent to: [--ExecutePreprocessor.allow_errors=True]\n",
"--stdin\n",
" read a single notebook file from stdin. Write the resulting notebook with default basename 'notebook.*'\n",
" Equivalent to: [--NbConvertApp.from_stdin=True]\n",
"--stdout\n",
" Write notebook output to stdout instead of files.\n",
" Equivalent to: [--NbConvertApp.writer_class=StdoutWriter]\n",
"--inplace\n",
" Run nbconvert in place, overwriting the existing notebook (only\n",
" relevant when converting to notebook format)\n",
" Equivalent to: [--NbConvertApp.use_output_suffix=False --NbConvertApp.export_format=notebook --FilesWriter.build_directory=]\n",
"--clear-output\n",
" Clear output of current file and save in place,\n",
" overwriting the existing notebook.\n",
" Equivalent to: [--NbConvertApp.use_output_suffix=False --NbConvertApp.export_format=notebook --FilesWriter.build_directory= --ClearOutputPreprocessor.enabled=True]\n",
"--no-prompt\n",
" Exclude input and output prompts from converted document.\n",
" Equivalent to: [--TemplateExporter.exclude_input_prompt=True --TemplateExporter.exclude_output_prompt=True]\n",
"--no-input\n",
" Exclude input cells and output prompts from converted document.\n",
" This mode is ideal for generating code-free reports.\n",
" Equivalent to: [--TemplateExporter.exclude_output_prompt=True --TemplateExporter.exclude_input=True --TemplateExporter.exclude_input_prompt=True]\n",
"--allow-chromium-download\n",
" Whether to allow downloading chromium if no suitable version is found on the system.\n",
" Equivalent to: [--WebPDFExporter.allow_chromium_download=True]\n",
"--disable-chromium-sandbox\n",
" Disable chromium security sandbox when converting to PDF..\n",
" Equivalent to: [--WebPDFExporter.disable_sandbox=True]\n",
"--show-input\n",
" Shows code input. This flag is only useful for dejavu users.\n",
" Equivalent to: [--TemplateExporter.exclude_input=False]\n",
"--embed-images\n",
" Embed the images as base64 dataurls in the output. This flag is only useful for the HTML/WebPDF/Slides exports.\n",
" Equivalent to: [--HTMLExporter.embed_images=True]\n",
"--sanitize-html\n",
" Whether the HTML in Markdown cells and cell outputs should be sanitized..\n",
" Equivalent to: [--HTMLExporter.sanitize_html=True]\n",
"--log-level=\n",
" Set the log level by value or name.\n",
" Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']\n",
" Default: 30\n",
" Equivalent to: [--Application.log_level]\n",
"--config=\n",
" Full path of a config file.\n",
" Default: ''\n",
" Equivalent to: [--JupyterApp.config_file]\n",
"--to=\n",
" The export format to be used, either one of the built-in formats\n",
" ['asciidoc', 'custom', 'html', 'latex', 'markdown', 'notebook', 'pdf', 'python', 'qtpdf', 'qtpng', 'rst', 'script', 'slides', 'webpdf']\n",
" or a dotted object name that represents the import path for an\n",
" ``Exporter`` class\n",
" Default: ''\n",
" Equivalent to: [--NbConvertApp.export_format]\n",
"--template=\n",
" Name of the template to use\n",
" Default: ''\n",
" Equivalent to: [--TemplateExporter.template_name]\n",
"--template-file=\n",
" Name of the template file to use\n",
" Default: None\n",
" Equivalent to: [--TemplateExporter.template_file]\n",
"--theme=\n",
" Template specific theme(e.g. the name of a JupyterLab CSS theme distributed\n",
" as prebuilt extension for the lab template)\n",
" Default: 'light'\n",
" Equivalent to: [--HTMLExporter.theme]\n",
"--sanitize_html=\n",
" Whether the HTML in Markdown cells and cell outputs should be sanitized.This\n",
" should be set to True by nbviewer or similar tools.\n",
" Default: False\n",
" Equivalent to: [--HTMLExporter.sanitize_html]\n",
"--writer=\n",
" Writer class used to write the\n",
" results of the conversion\n",
" Default: 'FilesWriter'\n",
" Equivalent to: [--NbConvertApp.writer_class]\n",
"--post=\n",
" PostProcessor class used to write the\n",
" results of the conversion\n",
" Default: ''\n",
" Equivalent to: [--NbConvertApp.postprocessor_class]\n",
"--output=\n",
" overwrite base name use for output files.\n",
" can only be used when converting one notebook at a time.\n",
" Default: ''\n",
" Equivalent to: [--NbConvertApp.output_base]\n",
"--output-dir=\n",
" Directory to write output(s) to. Defaults\n",
" to output to the directory of each notebook. To recover\n",
" previous default behaviour (outputting to the current\n",
" working directory) use . as the flag value.\n",
" Default: ''\n",
" Equivalent to: [--FilesWriter.build_directory]\n",
"--reveal-prefix=\n",
" The URL prefix for reveal.js (version 3.x).\n",
" This defaults to the reveal CDN, but can be any url pointing to a copy\n",
" of reveal.js.\n",
" For speaker notes to work, this must be a relative path to a local\n",
" copy of reveal.js: e.g., \"reveal.js\".\n",
" If a relative path is given, it must be a subdirectory of the\n",
" current directory (from which the server is run).\n",
" See the usage documentation\n",
" (https://nbconvert.readthedocs.io/en/latest/usage.html#reveal-js-html-slideshow)\n",
" for more details.\n",
" Default: ''\n",
" Equivalent to: [--SlidesExporter.reveal_url_prefix]\n",
"--nbformat=\n",
" The nbformat version to write.\n",
" Use this to downgrade notebooks.\n",
" Choices: any of [1, 2, 3, 4]\n",
" Default: 4\n",
" Equivalent to: [--NotebookExporter.nbformat_version]\n",
"\n",
"Examples\n",
"--------\n",
"\n",
" The simplest way to use nbconvert is\n",
"\n",
" > jupyter nbconvert mynotebook.ipynb --to html\n",
"\n",
" Options include ['asciidoc', 'custom', 'html', 'latex', 'markdown', 'notebook', 'pdf', 'python', 'qtpdf', 'qtpng', 'rst', 'script', 'slides', 'webpdf'].\n",
"\n",
" > jupyter nbconvert --to latex mynotebook.ipynb\n",
"\n",
" Both HTML and LaTeX support multiple output templates. LaTeX includes\n",
" 'base', 'article' and 'report'. HTML includes 'basic', 'lab' and\n",
" 'classic'. You can specify the flavor of the format used.\n",
"\n",
" > jupyter nbconvert --to html --template lab mynotebook.ipynb\n",
"\n",
" You can also pipe the output to stdout, rather than a file\n",
"\n",
" > jupyter nbconvert mynotebook.ipynb --stdout\n",
"\n",
" PDF is generated via latex\n",
"\n",
" > jupyter nbconvert mynotebook.ipynb --to pdf\n",
"\n",
" You can get (and serve) a Reveal.js-powered slideshow\n",
"\n",
" > jupyter nbconvert myslides.ipynb --to slides --post serve\n",
"\n",
" Multiple notebooks can be given at the command line in a couple of\n",
" different ways:\n",
"\n",
" > jupyter nbconvert notebook*.ipynb\n",
" > jupyter nbconvert notebook1.ipynb notebook2.ipynb\n",
"\n",
" or you can specify the notebooks list in a config file, containing::\n",
"\n",
" c.NbConvertApp.notebooks = [\"my_notebook.ipynb\"]\n",
"\n",
" > jupyter nbconvert --config mycfg.py\n",
"\n",
"To see all available configurables, use `--help-all`.\n",
"\n"
]
}
],
"source": [
"!npx nbconvert --help"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"The [`build:readme` script](https://github.com/iliazeus/node-nbconvert/blob/master/package.json#L7) is responsible for building this README,\n",
"so the above section always stays up-to-date with the corresponding `nbcovert` version.\n",
"\n",
"You can also use [JavaScript/TypeScript notebooks](https://github.com/microsoft/vscode-nodebook) to provide up-to-date examples\n",
"of using your package!\n",
"\n",
"\n",
"\n",
"Example: JavaScript\n",
"\n",
"(imagine this is a JavaScript notebook, not a Python one)"
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"0.30000000000000004\n"
]
}
],
"source": [
"!node -e 'console.log(\"\" + (0.1 + 0.2))'"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"## How?\n",
"\n",
"Three simple steps:\n",
"\n",
"1. package `nbconvert` with dependencies\n",
"\n",
" Python package management can be a bit of a mess. Especially since we want for this package to be installed via NPM.\n",
" We can't be sure if the user wants for Python packages to be installed via `pip`, or via system pacakge manager.\n",
" But we don't want to ask user to install them ourselves.\n",
"\n",
" Luckily, there are tools that can bundle a package and all its dependencies into a single file.\n",
" The tool I used was [`pex`](https://pypi.org/project/pex).\n",
" My [build script](https://github.com/iliazeus/node-nbconvert/blob/master/build.sh) installs `pex` into a local venv,\n",
" then packages `nbconvert` into `nbconvert.pex`, which can then be executed simply as `python nbconvert.pex`.\n",
"\n",
"2. make a \"binary devtool\" package\n",
"\n",
" The second step was to package `nbconvert.pex` in a way that would make it easy to use in NPM scripts.\n",
" That meant writing a [wrapper script](https://github.com/iliazeus/node-nbconvert/blob/master/run.js).\n",
" The single job of this script is to platform-independently run `python nbconvert.pex`, forwarding the CLI args\n",
" and IO streams, and then exit with the same exit code.\n",
"\n",
"3. publish to NPM with a specific versioning scheme\n",
"\n",
" Ideally, I would like for this package to use the same versions as the [`nbconvert` pypi package](https://pypi.org/project/nbconvert).\n",
" However, I would also like to be able to modify the wrapper scripts, build scripts and this README without it affecting this version scheme.\n",
" That is why this packaged is versioned using a `major.minor.revision` versioning scheme, where the `major.minor` part corresponds\n",
" to the major and minor versions of `nbconvert`, and the `revision` part is incremented every time I modify the wrapper stuff.\n",
" I could not use the `major.minor.patch-revision` scheme, because NPM treats the `revision` part as a \"pre-release tag\";\n",
" thus, `1.2.3-4` is considered _less_ recent than `1.2.3`.\n",
" The [build script](https://github.com/iliazeus/node-nbconvert/blob/master/build.sh#L8) takes care of fetching the right version of `nbconvert`."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3.10.8 64-bit",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.8"
},
"orig_nbformat": 4,
"vscode": {
"interpreter": {
"hash": "e7370f93d1d0cde622a1f8e1c04877d8463912d04d973331ad4851f04de6915a"
}
}
},
"nbformat": 4,
"nbformat_minor": 2
}