Add ability to evaluate separate code-blocks together.

[rmorshea]

It would be great if you could group code-blocks so they could be evaluated together.

I often find that I'll split up code blocks to make things easier to digest for the reader even when they ought to work when run together. For example:

Here we have an add function

def my_add_func(a, b):
    return a + B

You'd use it by running:

assert my_add_func(1, 2) == 3

This works linguistically but linters might complain because my_add_func does not exist in the same code block.

[adamtheturtle]

Thank you @rmorshea . How might you want this to work in your document? That is, how would you want to say "these code blocks are linked, and these other ones are not"?

[rmorshea]

I don't know how you're parsing things under the hood, or how this would play with MyST, but with CommonMark more generally it should be valid to put any text you want on the line with fence opening. Given that, you could support something like:

```language { "group": 1 }
...
```

On the implementation side you could json.loads(...) the string after language on the opening fence line. You could then concatenate the text from code blocks with the same "group" value when specified.

[adamtheturtle]

Thank you @rmorshea . This is an issue I have hit and worked around myself and I would be very happy to find a good solution.

There are a few other things to keep in mind here.

How to merge the two code blocks

• We can separate code blocks by 0/1/other blank lines
• We can pad all code blocks so that the line numbers in the file passed to the given command match the line numbers.
• We can give the user syntax to determine the number of blank lines to append/prepend to a code block

Each has trade-offs:

• A formatter will expect to have a sensible number of lines between code blocks, and may error in unclear ways.
• If we do not pad files according to the document source, line numbers in errors will not match line numbers in the source.
• Syntax to determine the number of blank lines to append/prepend adds complexity.

In place changes

Running a formatter, e.g. ruff format, against a document formats the code blocks in the document. We will lose that ability for grouped code blocks. How should that be communicated?

• We could error if there is a change made on a grouped code block
• We could silently ignore changes made on a grouped code block
• We could have options (with defaults) on the command line for this
• We could have options (with defaults) in the documentation source for this

[rmorshea]

Running a formatter, e.g. ruff format, against a document formats the code blocks in the document. We will lose that ability for grouped code blocks.

If linting and formatting are treated separately then I don't think this is true since, in my estimation, formatters have no need for code block grouping - it's only linters that need extra context from prior blocks on occasion.

[rmorshea]

I see that you're using Sybil under the hood. From my reading of their docs here it seems that they provide some doc test tooling that makes is possible for code blocks to be interpreted as one concatenated program unless broken up with a namespace clearing directive. With that in mind, you ought to be able to implement a linter that behaves similarly. Formatters, as mentioned above, can be handled differently since they don't do any static analysis.

[adamtheturtle]

If linting and formatting are treated separately

This is currently not the case. That is not to say that it can't become the case!

[rmorshea]

So, I gave this a think and realized that ruff check --fix combines both the needs of a linter and a formatter since it modifies code and checks for semantic correctness. Given that, it doesn't seem clear that you can always separate the needs of linters and formatters.

[rmorshea]

I'm gonna close this since, for the most part, just ignoring errors in docs is good enough. Feel free to re-open if you'd like.

[adamtheturtle]

Thanks @rmorshea . I'm going to re-open this as a prompt in the future - maybe something can be done