# ---
# jupyter:
#   jupytext:
#     text_representation:
#       extension: .sos
#       format_name: light
#       format_version: '1.5'
#       jupytext_version: 1.14.4
#   kernelspec:
#     display_name: SoS
#     language: sos
#     name: sos
# ---

# + [markdown] kernel="SoS"
# # How to convert SoS notebook to SoS script, and vise versa

# + [markdown] kernel="SoS"
# * **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
#   

# + [markdown] kernel="SoS"
# ## SoS -> ipynb

# + [markdown] kernel="SoS"
# You can convert an existing SoS script to the `.ipynb` format using command
# ```
# $ sos convert myscript.sos myscript.ipynb
# ```
#
# and open the resulting notebook from the web interface.
#
# Depending on how the sos file was written (or converted from `.ipynb` file), sos takes different approach in splitting content of the script into cells of ipython notebook. More specifically,
#
# 1. If the script contains cell spliting magic `%cell`, sos would split the sos script according to `%cell`, and restore proper metadata (e.g. kernel used for each cell) and execution index. Such a `.sos` file is usually exported from command `sos convert ipynb sos --all`.
# 2. If the script does not contain cell spliting magic, sos will split each step into a separate cell.

# + [markdown] kernel="SoS"
# The resulting `.ipynb` files have only input code and markdown cells. However, you can execute the notebook from command line if you add an `-e` (or `--execute`) option to the converter. That is to say, if you execute
#
# ```
# $ sos convert myscript.sos myscript.ipynb --execute
# ```
#
# You would get a notebook with both input and output cells, as if you have opened the non-executed `ipynb` file and selected `Cell -> Run all`.

# + [markdown] kernel="SoS"
# ## ipynb -> SoS

# + [markdown] kernel="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 the workflow defined in the jupyter notebook in the resulting `.sos` file, ignoring all cell magics, non-sos cells, and sos cells that do not start with section headers. The resulting `.sos` file is a proper SoS workflow and can be executed by the `sos` command in batch mode.
#
# If you would like to keep most of the information of the Jupyter notebook, you can convert the notebook using option `--all` (or `-a`),
#
# ```
# $ sos convert myscript.ipynb myscript.sos --all
# ```
#
# This option will export each cell with a `%cell` magic and record meta data in the `.sos` file. The resulting file can be converted back to `ipynb` format with minimal lose of information (without result), but might not be able to be executed in batch mode.

# + [markdown] kernel="SoS"
# ## Further reading
#
# * 

StarcoderdataJupyterScriptsDedupFiltered