Format code cells#
Code cell rendering behaviour is controlled with configuration at a global, per-file, or per-cell level, as outlined in the configuration section.
See the sections below for a description of these configuration option and their effect.
Number source lines#
You can control whether the number of source lines is displayed for code cells,
globally with nb_number_source_lines = True, per-file with number_source_lines in the notebook metadata, or per-cell with number_source_lines in the cell metadata.
For example:
```{code-cell} ipython3
---
mystnb:
number_source_lines: true
---
a = 1
b = 2
c = 1
```
1a = 1
2b = 2
3c = 1
stdout and stderr outputs#
Remove stdout or stderr#
In some cases you may not wish to display stdout/stderr outputs in your final documentation, for example, if they are only for debugging purposes.
You can tell MyST-NB to remove these outputs, per cell, using the remove-stdout and remove-stderr cell tags, like so:
```{code-cell} ipython3
:tags: [remove-input,remove-stdout,remove-stderr]
import pandas, sys
print("this is some stdout")
print("this is some stderr", file=sys.stderr)
# but what I really want to show is:
pandas.DataFrame({"column 1": [1, 2, 3]})
```
| column 1 | |
|---|---|
| 0 | 1 |
| 1 | 2 |
| 2 | 3 |
Alternatively, you can configure how stdout is dealt with at a global configuration level, using the nb_output_stderr configuration value.
This can be set to:
"show"(default): show all stderr (unless aremove-stderrtag is present)"remove": remove all stderr"remove-warn": remove all stderr, but log a warning to sphinx if any found"warn","error"or"severe": log to sphinx, at a certain level, if any found.
Group into single streams#
Cells may print multiple things to stdout and stderr.
For example, if a cell prints status updates throughout its execution, each of these is often printed to stdout.
By default, these outputs may be split across multiple items, and will be rendered as separate “chunks” in your built documentation.
If you’d like each of the outputs in stderr and stdout to be merged into a single stream for each, use the following configuration:
nb_merge_streams = True
This will ensure that all stderr and stdout outputs are merged into a single group.
This also makes cell outputs more deterministic.
Normally, slight differences in timing may result in different orders of stderr and stdout in the cell output, while this setting will sort them properly.
Outputs MIME priority#
When Jupyter executes a code cell it can produce multiple outputs, and each of these outputs can contain multiple MIME media types, for use by different output formats (like HTML or LaTeX).
MyST-NB stores a base priority dictionary for most of the common Sphinx builder names, mapping MIME types to a priority number (lower is higher priority):
import yaml
from myst_nb.core.render import base_render_priority
print(yaml.dump(base_render_priority()))
Show code cell output
applehelp:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 50
image/jp2: 80
image/jpeg: 60
image/png: 40
image/svg+xml: 90
image/tiff: 70
text/html: 30
text/latex: 110
text/markdown: 100
text/plain: 120
changes:
text/latex: 10
text/markdown: 20
text/plain: 30
devhelp:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 50
image/jpeg: 60
image/png: 40
text/html: 30
text/latex: 80
text/markdown: 70
text/plain: 90
dirhtml:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
dummy:
text/latex: 10
text/markdown: 20
text/plain: 30
epub:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
gettext:
text/latex: 10
text/markdown: 20
text/plain: 30
html:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
htmlhelp:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 50
image/jpeg: 60
image/png: 40
text/html: 30
text/latex: 80
text/markdown: 70
text/plain: 90
json:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
latex:
application/pdf: 10
image/jpeg: 30
image/png: 20
text/latex: 40
text/markdown: 50
text/plain: 60
linkcheck:
text/latex: 10
text/markdown: 20
text/plain: 30
man:
text/latex: 10
text/markdown: 20
text/plain: 30
pickle:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
pseudoxml:
text/latex: 10
text/markdown: 20
text/plain: 30
qthelp:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
readthedocs:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
readthedocsdirhtml:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
readthedocssinglehtml:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
readthedocssinglehtmllocalmedia:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
singlehtml:
application/javascript: 20
application/vnd.jupyter.widget-view+json: 10
image/gif: 60
image/jpeg: 70
image/png: 50
image/svg+xml: 40
text/html: 30
text/latex: 90
text/markdown: 80
text/plain: 100
texinfo:
image/gif: 30
image/jpeg: 20
image/png: 10
text/latex: 40
text/markdown: 50
text/plain: 60
text:
text/latex: 10
text/markdown: 20
text/plain: 30
xml:
text/latex: 10
text/markdown: 20
text/plain: 30
Items in this dictionary can be overridden by the nb_mime_priority_overrides configuration option, in your conf.py.
For example, the following configuration applies in order:
Sets
text/plainas the highest priority forhtmloutput.Disables
image/jpegforlatexoutputAdds a custom MIME type
customtypefor all builders (*applies to all builders)
nb_mime_priority_overrides = [
('html', 'text/plain', 0),
('latex', 'image/jpeg', None),
('*', 'customtype', 20)
]
Changed in version 0.14.0: nb_mime_priority_overrides replaces nb_render_priority
See also
Customise the render process, for a more advanced means of customisation.
Images and Figures#
With the default renderer, for any image types output by the code, we can apply formatting via cell metadata.
The top-level metadata key can be set using nb_cell_metadata_key in your conf.py, and is set to mystnb by default.
Then for the image we can apply all the variables of the standard image directive:
width: length or percentage (%) of the current line width
height: length
scale: integer percentage (the “%” symbol is optional)
align: “top”, “middle”, “bottom”, “left”, “center”, or “right”
classes: space separated strings
alt: string
Units of length are: ‘em’, ‘ex’, ‘px’, ‘in’, ‘cm’, ‘mm’, ‘pt’, ‘pc’
You can also wrap the output in a figure, that can include:
align: “left”, “center”, or “right”
caption: a string, which must contain a single paragraph and is rendered as MyST Markdown (subsequent paragraphs are added as a legend)
caption_before: a boolean, if true, the caption is rendered before the figure (default is false)
name: by which to reference the figure
classes: space separated strings
```{code-cell} ipython3
---
mystnb:
image:
width: 200px
alt: fun-fish
classes: shadow bg-primary
figure:
caption: |
Hey everyone its **party** time!
(and I'm a legend)
name: fun-fish-ref
---
from IPython.display import Image
Image("images/fun-fish.png")
```
from IPython.display import Image
Image("images/fun-fish.png")
Hey everyone its party time!#
(and I’m a legend)
Now we can link to the image from anywhere in our documentation: swim to the fish
You can create figures for any mime outputs, including tables:
```{code-cell} ipython3
---
mystnb:
figure:
align: center
caption_before: true
caption: This is my table caption, above the table
---
import pandas
df = pandas.DataFrame({"column 1": [1, 2, 3]})
df = df.style.set_table_attributes('class="dataframe align-center"')
df
```
import pandas
df = pandas.DataFrame({"column 1": [1, 2, 3]})
df = df.style.set_table_attributes('class="dataframe align-center"')
df
This is my table caption, above the table#
| column 1 | |
|---|---|
| 0 | 1 |
| 1 | 2 |
| 2 | 3 |
Markdown#
The format of output text/markdown can be specified by render_markdown_format configuration:
commonmark(default): Restricted to the CommonMark specification.gfm: Restricted to the GitHub-flavored markdown.Note, this requires the installation of the linkify-it-py package
myst: Uses the MyST parser with the same configuration as the current document.
CommonMark formatting will output basic Markdown syntax:
from IPython.display import display, Markdown
display(Markdown('**_some_ markdown** and an [a reference](https://example.com)!'))
some markdown and an a reference!
and even internal images can be rendered!
display(Markdown(''))
But setting the Markdown format to myst will allow for more advanced formatting,
such as including internal references, tables, and even other directives, either using:
myst_render_markdown_format = "myst"in theconf.pyto set globally, ormarkdown_formatin the cell metadata to set per-cell.
````{code-cell} ipython3
---
mystnb:
markdown_format: myst
---
display(Markdown('**_some_ markdown** and an [internal reference](render/output/markdown)!'))
display(Markdown("""
| a | b | c |
|---|---|---|
| 1 | 2 | 3 |
"""))
display(Markdown("""
```{note}
A note admonition!
```
"""))
````
The parsed Markdown is integrated into the wider documentation, and so it is possible, for example, to include internal references:
display(Markdown('**_some_ markdown** and an [internal reference](render/output/markdown)!'))
display(Markdown("""
| a | b | c |
|---|---|---|
| 1 | 2 | 3 |
"""))
display(Markdown("""
```{note}
A note admonition!
```
"""))
ANSI Outputs#
By default, the standard output/error streams and text/plain MIME outputs may contain ANSI escape sequences to change the text and background colors.
import sys
print("BEWARE: \x1b[1;33;41mugly colors\x1b[m!", file=sys.stderr)
print("AB\x1b[43mCD\x1b[35mEF\x1b[1mGH\x1b[4mIJ\x1b[7m"
"KL\x1b[49mMN\x1b[39mOP\x1b[22mQR\x1b[24mST\x1b[27mUV")
ABCDEFGHIJKLMNOPQRSTUV
BEWARE: ugly colors!
This uses the built-in AnsiColorLexer pygments lexer.
You can change the lexer used in the conf.py, for example to turn off lexing:
nb_render_text_lexer = "none"
The following code[1] shows the 8 basic ANSI colors it is based on. Each of the 8 colors has an “intense” variation, which is used for bold text.
text = " XYZ "
formatstring = "\x1b[{}m" + text + "\x1b[m"
print(
" " * 6
+ " " * len(text)
+ "".join("{:^{}}".format(bg, len(text)) for bg in range(40, 48))
)
for fg in range(30, 38):
for bold in False, True:
fg_code = ("1;" if bold else "") + str(fg)
print(
" {:>4} ".format(fg_code)
+ formatstring.format(fg_code)
+ "".join(
formatstring.format(fg_code + ";" + str(bg)) for bg in range(40, 48)
)
)
40 41 42 43 44 45 46 47
30 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;30 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
31 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;31 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
32 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;32 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
33 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;33 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
34 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;34 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
35 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;35 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
36 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;36 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
37 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
1;37 XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ XYZ
Note
ANSI also supports a set of 256 indexed colors. This is currently not supported, but we hope to introduce it at a later date (raise an issue on the repository if you require it!).
Customise the render process#
The render process is governed by subclasses of NbElementRenderer, which dictate how to create the docutils AST nodes for elements of the notebook.
Implementations are loaded via Python entry points, in the myst_nb.renderers group.
So it is possible to inject your own subclass to fully override rendering.
For example, the renderer loaded in this package is:
[project.entry-points."myst_nb.renderers"]
default = "myst_nb.core.render:NbElementRenderer"
You can then select the renderer plugin in your conf.py:
nb_render_plugin = "default"
Plugins can also override rendering of particular output MIME types,
using the myst_nb.mime_renderers entry point group to supply functions with signature: MimeRenderPlugin.
For example myst_nb.core.render.ExampleMimeRenderPlugin, is loaded in this package:
[project.entry-points."myst_nb.mime_renderers"]
example = "myst_nb.core.render:ExampleMimeRenderPlugin"
Meaning we can now render custommimetype in all output formats:
from IPython.display import display
display({"custommimetype": "Some text"}, raw=True)
This is a custom mime type, with content: ‘Some text’