Simpler code blocks

[certik]

When looking at https://github.com/executablebooks/MyST-Parser/blob/f32bd380bdec755238566fa91352f9ed1d491036/docs/examples/wealth_dynamics_md.md, currently the code blocks are done as follows:

```{code-block} python
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline

import quantecon as qe
from numba import njit, jitclass, float64, prange
```

Would it make sense to for the following to be a shortcut for the above:

```python
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline

import quantecon as qe
from numba import njit, jitclass, float64, prange
```

As that is the common syntax to denote code blocks at GitHub / GitLab, etc.

[choldgraf]

That's actually a different functionality than a regular code block - myst supports the same style of code blocks that commonmark does (what you suggest above). The {code-block} syntax is to explicitly designate Jupyter Notebook code blocks that are executable

[certik]

So when showing code examples in documentation, which code block do you recommend people to use? I am a bit confused.

[choldgraf]

for the vast majority of people, they should use:

```python
print("mycode")
```

same as any other markdown.

If what you want is to convert your documentation page into a notebook, execute it at runtime, and insert the outputs into the page, then use

```{code-cell}
print("mycode")
```

See https://myst-nb.readthedocs.io/en/latest/use/markdown.html for more information about this

[certik]

Ah I see. Thanks for the explanation. I am going to close this issue, I think it's already implemented as I would expect. I misunderstood the example document.

[choldgraf]

Which page were you looking at? Sounds like we could clarify this better

[choldgraf]

Or was it only in the wealth dynamics example that you shared above?

[certik]

Yes, this one: https://myst-parser.readthedocs.io/en/latest/examples/wealth_dynamics_md.html

[certik]

This was prominently linked at the front page, so I clicked on it to see the details of the syntax.

[certik]

Btw, another feature I've been long missing is side by side code blocks, which you also implemented. Very exciting, I can now convert this page: https://www.fortran90.org/src/rosetta.html which was a pain to maintain in rst.

[chrisjsewell]

another feature I've been long missing is side by side code blocks

FYI @certik you may also want to check out the https://sphinx-panels.readthedocs.io extension for this use case, which I've literally just created this week for another project 😁 (as with any sphinx directive, it can also be used in MyST)

[certik]

@chrisjsewell cool ---- are the panels for things like chapters of a book?

[choldgraf]

For chapters of a book, I would recommend either the sphinx-book-theme (https://sphinx-book-theme.readthedocs.io/en/latest/) or its older brother, jupyter book (https://jupyterbook.org/intro.html) - both are projects of the same collaboration that has created the myst-parser

[chrisjsewell]

Well you can use them for anything really. But the use case in mind is just for small sections of a page; as used here: https://pandas.pydata.org/docs/getting_started/index.html, or thumbnail links like: https://pandas.pydata.org/docs/