@jupytext improvements ready for review

[Edward K. Ream]

PR #4138 (@jupytext improvements) is ready for review. All tests pass and the generated code looks reasonable to me.

This PR causes Leo to split @jupytext nodes into a flat list of child nodes. This splitting happens only the first time Leo reads such a node. You can inhibit this action by adding any child node (including an empty node) to the @jupytext tree.

The algorithm follows Thomas's prototype script closely, but not exactly. This PR does not attempt to determine the indentation level of markdown nodes. Any such enhancements must wait until Leo 6.8.3 or later. It's time to test what we have.

Edward

[Thomas Passin]

I tried importing the two files I've been using for my experiments and they both seem right.  I didn't try round-tripping the notebook files, and I didn't look closely to see if there were any extra blank lines inserted.

I do have two suggestions, though, both trivial to implement.

1. Only use the first 6 words of the first line for the headline, the way my script did.  It's much more readable that way.  Using the long headlines as the importer currently does makes for headlines that are harder to read and more annoying without being helpful.

2. Put an @nocolor directive at the top of each markdown cell.  Otherwise the leading comment signs cause the colorizer to syntax-color the cell's content as comments, and with most themes that makes the text harder to read.

[Edward K. Ream]

On Tuesday, October 29, 2024 at 6:55:25 PM UTC-5 Thomas wrote:

I do have two suggestions, though, both trivial to implement.

1. Only use the first 6 words of the first line for the headline, the way my script did. 

The new jtm.compute_headline method does a much better job of computing headlines. You'll like it.

2. Put an @nocolor directive at the top of each markdown cell. 

I'm not going to do this because @nocolor suppresses all coloring.

Edward

[Edward K. Ream]

On Tuesday, October 29, 2024 at 6:21:00 PM UTC-5 Edward K. Ream wrote:

PR #4138 (@jupytext improvements) is ready for review. All tests pass and the generated code looks reasonable to me.

Recent revs contain several important improvements. See the PR for details.

HaveF has approved this PR, but I'll wait a bit longer for comments.

Edward

[Thomas Passin]

On Wednesday, October 30, 2024 at 6:51:00 AM UTC-4 Edward K. Ream wrote:

2. Put an @nocolor directive at the top of each markdown cell. 

I'm not going to do this because @nocolor suppresses all coloring.

Then add @color to code cells.  They are the ones that should be colorized.

[Thomas Passin]

On Wednesday, October 30, 2024 at 6:51:00 AM UTC-4 Edward K. Ream wrote:

I do have two suggestions, though, both trivial to implement.

1. Only use the first 6 words of the first line for the headline, the way my script did. 

The new jtm.compute_headline method does a much better job of computing headlines. You'll like it.

I don't love seeing the leading "#"s in the headline, though. E.g., ## 1. Specifying element type.

[HaveF HaveF]

I don't love seeing the leading "#"s in the headline, though. E.g., ## 1. Specifying element type.

The starting point of my suggestion is that since all our nodes are at the same level, we can only know which level it is through the `#` in the markdown heading, which is convenient for quickly finding the location when switching between jupyter lab and Leo. In addition, this mark can also be distinguished from ordinary cells.

 

[Edward K. Ream]

Then add @color to code cells.  They are the ones that should be colorized.

I'll discuss easy, Leonine, workarounds soon in an ENB.

Edward

[Edward K. Ream]

On Wed, Oct 30, 2024 at 8:48 AM HaveF HaveF <iamap...@gmail.com> wrote:

I don't love seeing the leading "#"s in the headline, though. E.g., ## 1. Specifying element type.

The starting point of my suggestion is that since all our nodes are at the same level, we can only know which level it is through the `#` in the markdown heading, which is convenient for quickly finding the location when switching between jupyter lab and Leo. In addition, this mark can also be distinguished from ordinary cells.

I agree with you, not Thomas. The '#' markers (in the headlines of markdown nodes) are exactly what we want to see. This page of example notebooks contains several .ipynb files. To see the sample notebooks properly, launch jupyter from the button on this page!

For example, I downloaded (from jupyter) example-data-analysis.ipynb and rearranged the resulting nodes by hand. The child nodes became:

<< prefix >>

# Loading and Analyzing Data

## Load the air quality data

## Aggregate and average MA data by city

## Visually Inspect the Data

All the python nodes became children of these markdown "topic" nodes.

What could be clearer than this?

Edward

P.S. It's more "logical" to move the "##" nodes so they are children of the # Loading and Analyzing Data. But this is a judgement call. I don't want @jupytext to indent nodes automatically because there is no single "right" way.

Lastly, reorganizing the outline can be done (within Leo) at any time. It takes only seconds to do so.

EKR