Code (and Code-Block) vs CodeCell

[rowanc1]

There are directives that define codeBlocks that have the same properties as code, and we have reduced that down to a single node in the spec. I think we need to carry another property to differentiate that!

Not quite sure what it is, maybe executable? Right now this allows thebe to target as well as changes the view of the UI (see below).

CodeBlock:

Code:

[fwkoch]

Hmm, could be as simple as just an additional executable property. Gets a bit dicey piling up more properties though. Does executable imply editable? Or is editable a separate property - that would make other properties like emphasizeLines less meaningful because lines could change. At some point, we can also just defer to data rather than adding more and more properties...

Another thought - thinking about jupyter, would an executable code block always be its own cell, regardless of the presence of block breaks +++? i.e. would this be two cells or one:

+++
# Some Markdown

blah blah blah

```{code-block} python
:executable: true

+++

If that's one cell... it means just the `code` node is probably ok(?), and there's maybe a little jupyter magic when a `+++` block only has executable code. If that's two cells... it means code block potentially needs properties for code _and_ block and should maybe be a separate node type.

[chrisjsewell]

It should follow myst-nb and have code cells. These are very different to code blocks

[rowanc1]

Are you saying introduce a new node type beyond: https://executablebooks.github.io/myst-spec/myst.schema.html#code

What is the name of that? This is the "Jupyter" code block.

What are the other differences?

[rowanc1]

From the meeting with @chrisjsewell and @fwkoch today:

• Introduce a codeCell (The directive name is 'code-cell')

  • this follow nb-format (metadata)
  • This may or may not be a directive, but doesn't matter from the spec side.
  • This may be enforced to be at top level in some cases (myst-nb)

• Rename blockBreak --> cellBreak?

• And block --> cell

[mmcky]

@chrisjsewell there has been some confusion from authors I have spoken with between:

Static code highlighting

```python

The `code-block` from `sphinx`

and the `code-cell` from `myst-nb`. While I understand the need for `code-cell` in `myst-nb` it is tied to `jupyter` concept of `cells`. Wondering if `myst` should be more general and treat `code` as a first class executable type, and introduce more static concepts for displaying code.

Executable Code:

and static / display code could use:

:no-execute:

or 

Just a thought while we are developing a spec for the future. 

[chrisjsewell]

Wondering if myst should be more general and treat code as a first class executable type

To clarify, myst-spec, at least in its initial iteration should not concern itself with code execution, that is a lot more complex than I feel you are giving it credit for.

1. code execution cells are not directives, they are semantically very different. In myst-nb they are made to "look" like directives, for convenience, but are treated very differently
2. code execution cells do not exist in isolation; if you introduce execution, then you also need to introduce to the specification the full semantics of a jupyter notebook, e.g. kernel specification, and how code is actually executed. That is going to require a lot more discussion

[mmcky]

hey @chrisjsewell yeah I know this is a complex issue for sure.

So just to clarify then myst-spec (at least initially) is just about rendering markup + some standardised behaviour for a minimum set of directives and roles?

Do you think tying the terminology of cell is a good thing for supporting executable content then?

code execution cells do not exist in isolation; if you introduce execution, then you also need to introduce to the specification the full semantics of a jupyter notebook, e.g. kernel specification, and how code is actually executed. That is going to require a lot more discussion

This is a good argument to do so.

[chrisjsewell]

So just to clarify then myst-spec (at least initially) is just about rendering markup + some standardised behaviour for a minimum set of directives and roles?

Indeed, I feel we should try to "lock-down" this first, which is complex enough 😅, before introducing the intricacies of code execution. Although, this does not have to stop us from thinking about it beforehand, and we can have an eye on making this as easy as possible to integrate in.

For example, it is desirable to first ensure https://github.com/executablebooks/MyST-Parser is "compliant" with myst-spec, but myst-parser itself doesn't have code execution functionality