Format conversion

• Difficulty level: easy
• Time need to lean: 10 minutes or less
• Key points:
  • sos convert file.ipynb file.sos converts notebook to sos script
  • sos convert file.sos file.ipynb converts sos script to sos notebook

SoS -> ipynb

You can convert an existing SoS script to the .ipynb format using command

$ sos convert myscript.sos myscript.ipynb

ipynb -> SoS

A Jupyter notebook can contain markdown cell and code cell with different kernels, and a sos cell might or might not contain a real sos step (with section header).

You can save a Jupyter notebook with SoS kernel to a SoS script using File -> Download As -> SoS from the browser, or using command

$ sos convert myscript.ipynb myscript.sos

The conversion process will export only the embeded workflow to .sos file, ignoring all other content of the notebook.

ipynb -> HTML

Command sos convert my.ipynb my.html --template essentially calls jupyter nbconvert --to html to convert notebook to HTML format, with additional templates provided by SoS Notebook.

SoS provides the following templates

Where:

• code highlighting: Jupyter can hilight sos source code using a static syntax hilighter. The output is lightweight but not as nice as the codemirror highlighter.
• TOC: Automatically generate a table of content to the left of the page.
• Hide Cell: HTML page by default only displays only markdown and selected ouptput cells (cells with report_cell tag, output of cells with report_output tag). A control panel to the left top corner of the page can be used to show all content

ipynb -> pdf

This command essentially calls command jupyter nbconvert --to pdf to convert notebook to PDF format.

ipynb -> md

This command essentially calls command jupyter nbconvert --to markdown to convert notebook to Markdown format.

ipynb -> ipynb

This command converts a Jupyter notebook in another kernel to a SoS notebook, with the original kernel language as the language of each code cell.

If the original notebook has kernel python3, an option --python3-to-sos can be used to convert code cells to SoS.

This converter will copy the input notebook to output if the notebook is already a SoS notebook. However, if an option --inplace is specified, it will overwrite the original notebook with the converted one.

Note that if you already have a non-SoS notebook opened in Jupyter, you can simply use

Kernel -> Change kernel -> sos

to convert the kernel to SoS. You can then use the global language selector to select the appropriate default langauge for the notebook and re-execute the notebook to set the language to each cell.

SoS -> HTML

The sos to html converter converts .sos script to HTML format. It can be either written to a HTML file, or to standard output if option --to html is specified without a destination filename.

The converter also accepts a number of parameters (as shown above). The raw parameter adds a URL to filename in the HTML file so that you can link to the raw .sos file from the .html output. The linenos adds line numbers, and style allows you to choose from a number of pre-specified styles. Finally, the view option would open the resulting HTML file in a browser.

For example,

sos convert ../examples/update_toc.sos --to html --view --style xcode

would show a HTML file as