Automatically convert percent cell names to markdown headings

[thangleiter]

I use jupytext to share scripts/notebooks between Jupyter and Spyder. I store the files in percent format:

Jupytext header

# ---
# jupyter:
#   jupytext:
#     cell_metadata_json: true
#     formats: py:percent
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#       jupytext_version: 1.16.4
#   kernelspec:
#     display_name: Python 3 (ipykernel)
#     language: python
#     name: python3
# ---

Spyder recognizes text that comes after the percent symbols as headings and uses those in the outline pane. For example:

# %% bar
...
# %% foo
...
# %%% foobar
...

is recognized as

As far as I can tell, Jupytext does not use this information. To have meaningful cell headings in notebook format (which Jupyter lab for example uses for its outline pane), my jupytext scripts therefore have redundancy like this

# %% [markdown]
## bar

# %% bar
...
# %% [markdown]
## foo

# %% foo
...
# %% [markdown]
### foobar

# %%% foobar
...

My suggestion would hence be to automatically convert the text after percent symbols into markdown cells containing the text as a heading just above the corresponding code cell.

[mwouts]

Hey @thangleiter , thank you for suggesting this!

Well currently the Spyder cell titles are preserved in the cell metadata - which I agree you don't get to see in the notebook. FYI I have been working on an option that would map the cell title to the cell id (#1270) - but I don't think the cell id is easier to see in the notebook editor neither.

I don't think I can implement the two-way conversion that you suggest above, but if you are interested I think I can help you write a script that would create the markdown headings.

[thangleiter]

Thanks for the suggestions!

Well currently the Spyder cell titles are preserved in the cell metadata - which I agree you don't get to see in the notebook. FYI I have been working on an option that would map the cell title to the cell id (#1270) - but I don't think the cell id is easier to see in the notebook editor neither.

Yeah, I don't think so. The outline is handy for me because I never execute notebooks/cells sequentially (top to bottom) but rather use the script to collect different measurement instructions for our experiment. Hence I jump back and forth all the time and it's handy to have the headings for that so that I can just click on the heading in the outline to jump to the cell for the measurement I want to run next.

I don't think I can implement the two-way conversion that you suggest above, but if you are interested I think I can help you write a script that would create the markdown headings.

Would I be able to hook up the script to jupytext so that each time I open a notebook from the percent file they are generated? In that case that'd be perfect!