{
"cells": [
{
"cell_type": "markdown",
"id": "9de2a7f2",
"metadata": {},
"source": [
"(render/code-cells)=\n",
"# Format code cells\n",
"\n",
"Code cell rendering behaviour is controlled with configuration at a global, per-file, or per-cell level, as outlined in the [configuration section](config/intro).\n",
"\n",
"See the sections below for a description of these configuration option and their effect.\n",
"\n",
"(render/input/number)=\n",
"## Number source lines\n",
"\n",
"You can control whether the number of source lines is displayed for code cells,\n",
"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.\n",
"For example:\n",
"\n",
"````markdown\n",
"```{code-cell} ipython3\n",
"---\n",
"mystnb:\n",
" number_source_lines: true\n",
"---\n",
"a = 1\n",
"b = 2\n",
"c = 1\n",
"```\n",
"````"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "a1d677b7",
"metadata": {
"mystnb": {
"number_source_lines": true
}
},
"outputs": [],
"source": [
"a = 1\n",
"b = 2\n",
"c = 1"
]
},
{
"cell_type": "markdown",
"id": "8dea5802",
"metadata": {},
"source": [
"(render/output/stdout-stderr)=\n",
"## stdout and stderr outputs\n",
"\n",
"(render/output/stderr)=\n",
"### Remove stdout or stderr\n",
"\n",
"In some cases you may not wish to display stdout/stderr outputs in your final documentation,\n",
"for example, if they are only for debugging purposes.\n",
"\n",
"You can tell MyST-NB to remove these outputs, per cell, using the `remove-stdout` and `remove-stderr` [cell tags](https://jupyter-notebook.readthedocs.io/en/stable/changelog.html#cell-tags), like so:\n",
"\n",
"````md\n",
"```{code-cell} ipython3\n",
":tags: [remove-input,remove-stdout,remove-stderr]\n",
"\n",
"import pandas, sys\n",
"print(\"this is some stdout\")\n",
"print(\"this is some stderr\", file=sys.stderr)\n",
"# but what I really want to show is:\n",
"pandas.DataFrame({\"column 1\": [1, 2, 3]})\n",
"```\n",
"````"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "d9fa8f3b",
"metadata": {
"tags": [
"remove-input",
"remove-stdout",
"remove-stderr"
]
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"this is some stdout\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"this is some stderr\n"
]
},
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" column 1 | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 1 | \n",
"
\n",
" \n",
" | 1 | \n",
" 2 | \n",
"
\n",
" \n",
" | 2 | \n",
" 3 | \n",
"
\n",
" \n",
"
\n",
"
\n",
" \n",
" \n",
" | | \n",
" column 1 | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 1 | \n",
"
\n",
" \n",
" | 1 | \n",
" 2 | \n",
"
\n",
" \n",
" | 2 | \n",
" 3 | \n",
"
\n",
" \n",
"
\n"
],
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import pandas\n",
"df = pandas.DataFrame({\"column 1\": [1, 2, 3]})\n",
"df = df.style.set_table_attributes('class=\"dataframe align-center\"')\n",
"df"
]
},
{
"cell_type": "markdown",
"id": "2469bc1d",
"metadata": {},
"source": [
"(render/output/markdown)=\n",
"## Markdown\n",
"\n",
"The format of output `text/markdown` can be specified by `render_markdown_format` configuration:\n",
"\n",
"- `commonmark` (default): Restricted to the [CommonMark specification](https://commonmark.org/).\n",
"- `gfm`: Restricted to the [GitHub-flavored markdown](https://github.github.com/gfm/).\n",
" - Note, this requires the installation of the [linkify-it-py package](https://pypi.org/project/linkify-it-py)\n",
"- `myst`: Uses [the MyST parser](https://myst-parser.readthedocs.io/en/latest/) with the same configuration as the current document.\n",
"\n",
"CommonMark formatting will output basic Markdown syntax:"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "c9ef1ffe",
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"**_some_ markdown** and an [a reference](https://example.com)!"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"from IPython.display import display, Markdown\n",
"display(Markdown('**_some_ markdown** and an [a reference](https://example.com)!'))"
]
},
{
"cell_type": "markdown",
"id": "f47b3df6",
"metadata": {},
"source": [
"and even internal images can be rendered!"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "168e1e23",
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(Markdown(''))"
]
},
{
"cell_type": "markdown",
"id": "3aa29f66",
"metadata": {},
"source": [
"But setting the Markdown format to `myst` will allow for more advanced formatting,\n",
"such as including internal references, tables, and even other directives, either using:\n",
"\n",
"- `myst_render_markdown_format = \"myst\"` in the `conf.py` to set globally, or\n",
"- `markdown_format` in the cell metadata to set per-cell.\n",
"\n",
"`````md\n",
"````{code-cell} ipython3\n",
"---\n",
"mystnb:\n",
" markdown_format: myst\n",
"---\n",
"display(Markdown('**_some_ markdown** and an [internal reference](render/output/markdown)!'))\n",
"display(Markdown(\"\"\"\n",
"| a | b | c |\n",
"|---|---|---|\n",
"| 1 | 2 | 3 |\n",
"\"\"\"))\n",
"display(Markdown(\"\"\"\n",
"```{note}\n",
"A note admonition!\n",
"```\n",
"\"\"\"))\n",
"````\n",
"`````\n",
"\n",
"The parsed Markdown is integrated into the wider documentation, and so it is possible, for example, to include internal references:"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "bcc189b8",
"metadata": {
"mystnb": {
"markdown_format": "myst"
}
},
"outputs": [
{
"data": {
"text/markdown": [
"**_some_ markdown** and an [internal reference](render/output/markdown)!"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/markdown": [
"\n",
"| a | b | c |\n",
"|---|---|---|\n",
"| 1 | 2 | 3 |\n"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/markdown": [
"\n",
"```{note}\n",
"A note admonition!\n",
"```\n"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(Markdown('**_some_ markdown** and an [internal reference](render/output/markdown)!'))\n",
"display(Markdown(\"\"\"\n",
"| a | b | c |\n",
"|---|---|---|\n",
"| 1 | 2 | 3 |\n",
"\"\"\"))\n",
"display(Markdown(\"\"\"\n",
"```{note}\n",
"A note admonition!\n",
"```\n",
"\"\"\"))"
]
},
{
"cell_type": "markdown",
"id": "f76bdc73",
"metadata": {},
"source": [
"(render/output/ansi)=\n",
"## ANSI Outputs\n",
"\n",
"By default, the standard output/error streams and text/plain MIME outputs may contain ANSI escape sequences to change the text and background colors."
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "cc155a57",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"AB\u001b[43mCD\u001b[35mEF\u001b[1mGH\u001b[4mIJ\u001b[7mKL\u001b[49mMN\u001b[39mOP\u001b[22mQR\u001b[24mST\u001b[27mUV\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"BEWARE: \u001b[1;33;41mugly colors\u001b[m!\n"
]
}
],
"source": [
"import sys\n",
"print(\"BEWARE: \\x1b[1;33;41mugly colors\\x1b[m!\", file=sys.stderr)\n",
"print(\"AB\\x1b[43mCD\\x1b[35mEF\\x1b[1mGH\\x1b[4mIJ\\x1b[7m\"\n",
" \"KL\\x1b[49mMN\\x1b[39mOP\\x1b[22mQR\\x1b[24mST\\x1b[27mUV\")"
]
},
{
"cell_type": "markdown",
"id": "8d6cece6",
"metadata": {},
"source": [
"This uses the built-in {py:class}`~myst_nb.core.lexers.AnsiColorLexer` [pygments lexer](https://pygments.org/).\n",
"You can change the lexer used in the `conf.py`, for example to turn off lexing:\n",
"\n",
"```python\n",
"nb_render_text_lexer = \"none\"\n",
"```\n",
"\n",
"The following code[^acknowledge] shows the 8 basic ANSI colors it is based on.\n",
"Each of the 8 colors has an “intense” variation, which is used for bold text.\n",
"\n",
"[^acknowledge]: Borrowed from [nbsphinx](https://nbsphinx.readthedocs.io/en/0.7.1/code-cells.html#ANSI-Colors)!"
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "9dd7f05a",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" 40 41 42 43 44 45 46 47 \n",
" 30 \u001b[30m XYZ \u001b[m\u001b[30;40m XYZ \u001b[m\u001b[30;41m XYZ \u001b[m\u001b[30;42m XYZ \u001b[m\u001b[30;43m XYZ \u001b[m\u001b[30;44m XYZ \u001b[m\u001b[30;45m XYZ \u001b[m\u001b[30;46m XYZ \u001b[m\u001b[30;47m XYZ \u001b[m\n",
" 1;30 \u001b[1;30m XYZ \u001b[m\u001b[1;30;40m XYZ \u001b[m\u001b[1;30;41m XYZ \u001b[m\u001b[1;30;42m XYZ \u001b[m\u001b[1;30;43m XYZ \u001b[m\u001b[1;30;44m XYZ \u001b[m\u001b[1;30;45m XYZ \u001b[m\u001b[1;30;46m XYZ \u001b[m\u001b[1;30;47m XYZ \u001b[m\n",
" 31 \u001b[31m XYZ \u001b[m\u001b[31;40m XYZ \u001b[m\u001b[31;41m XYZ \u001b[m\u001b[31;42m XYZ \u001b[m\u001b[31;43m XYZ \u001b[m\u001b[31;44m XYZ \u001b[m\u001b[31;45m XYZ \u001b[m\u001b[31;46m XYZ \u001b[m\u001b[31;47m XYZ \u001b[m\n",
" 1;31 \u001b[1;31m XYZ \u001b[m\u001b[1;31;40m XYZ \u001b[m\u001b[1;31;41m XYZ \u001b[m\u001b[1;31;42m XYZ \u001b[m\u001b[1;31;43m XYZ \u001b[m\u001b[1;31;44m XYZ \u001b[m\u001b[1;31;45m XYZ \u001b[m\u001b[1;31;46m XYZ \u001b[m\u001b[1;31;47m XYZ \u001b[m\n",
" 32 \u001b[32m XYZ \u001b[m\u001b[32;40m XYZ \u001b[m\u001b[32;41m XYZ \u001b[m\u001b[32;42m XYZ \u001b[m\u001b[32;43m XYZ \u001b[m\u001b[32;44m XYZ \u001b[m\u001b[32;45m XYZ \u001b[m\u001b[32;46m XYZ \u001b[m\u001b[32;47m XYZ \u001b[m\n",
" 1;32 \u001b[1;32m XYZ \u001b[m\u001b[1;32;40m XYZ \u001b[m\u001b[1;32;41m XYZ \u001b[m\u001b[1;32;42m XYZ \u001b[m\u001b[1;32;43m XYZ \u001b[m\u001b[1;32;44m XYZ \u001b[m\u001b[1;32;45m XYZ \u001b[m\u001b[1;32;46m XYZ \u001b[m\u001b[1;32;47m XYZ \u001b[m\n",
" 33 \u001b[33m XYZ \u001b[m\u001b[33;40m XYZ \u001b[m\u001b[33;41m XYZ \u001b[m\u001b[33;42m XYZ \u001b[m\u001b[33;43m XYZ \u001b[m\u001b[33;44m XYZ \u001b[m\u001b[33;45m XYZ \u001b[m\u001b[33;46m XYZ \u001b[m\u001b[33;47m XYZ \u001b[m\n",
" 1;33 \u001b[1;33m XYZ \u001b[m\u001b[1;33;40m XYZ \u001b[m\u001b[1;33;41m XYZ \u001b[m\u001b[1;33;42m XYZ \u001b[m\u001b[1;33;43m XYZ \u001b[m\u001b[1;33;44m XYZ \u001b[m\u001b[1;33;45m XYZ \u001b[m\u001b[1;33;46m XYZ \u001b[m\u001b[1;33;47m XYZ \u001b[m\n",
" 34 \u001b[34m XYZ \u001b[m\u001b[34;40m XYZ \u001b[m\u001b[34;41m XYZ \u001b[m\u001b[34;42m XYZ \u001b[m\u001b[34;43m XYZ \u001b[m\u001b[34;44m XYZ \u001b[m\u001b[34;45m XYZ \u001b[m\u001b[34;46m XYZ \u001b[m\u001b[34;47m XYZ \u001b[m\n",
" 1;34 \u001b[1;34m XYZ \u001b[m\u001b[1;34;40m XYZ \u001b[m\u001b[1;34;41m XYZ \u001b[m\u001b[1;34;42m XYZ \u001b[m\u001b[1;34;43m XYZ \u001b[m\u001b[1;34;44m XYZ \u001b[m\u001b[1;34;45m XYZ \u001b[m\u001b[1;34;46m XYZ \u001b[m\u001b[1;34;47m XYZ \u001b[m\n",
" 35 \u001b[35m XYZ \u001b[m\u001b[35;40m XYZ \u001b[m\u001b[35;41m XYZ \u001b[m\u001b[35;42m XYZ \u001b[m\u001b[35;43m XYZ \u001b[m\u001b[35;44m XYZ \u001b[m\u001b[35;45m XYZ \u001b[m\u001b[35;46m XYZ \u001b[m\u001b[35;47m XYZ \u001b[m\n",
" 1;35 \u001b[1;35m XYZ \u001b[m\u001b[1;35;40m XYZ \u001b[m\u001b[1;35;41m XYZ \u001b[m\u001b[1;35;42m XYZ \u001b[m\u001b[1;35;43m XYZ \u001b[m\u001b[1;35;44m XYZ \u001b[m\u001b[1;35;45m XYZ \u001b[m\u001b[1;35;46m XYZ \u001b[m\u001b[1;35;47m XYZ \u001b[m\n",
" 36 \u001b[36m XYZ \u001b[m\u001b[36;40m XYZ \u001b[m\u001b[36;41m XYZ \u001b[m\u001b[36;42m XYZ \u001b[m\u001b[36;43m XYZ \u001b[m\u001b[36;44m XYZ \u001b[m\u001b[36;45m XYZ \u001b[m\u001b[36;46m XYZ \u001b[m\u001b[36;47m XYZ \u001b[m\n",
" 1;36 \u001b[1;36m XYZ \u001b[m\u001b[1;36;40m XYZ \u001b[m\u001b[1;36;41m XYZ \u001b[m\u001b[1;36;42m XYZ \u001b[m\u001b[1;36;43m XYZ \u001b[m\u001b[1;36;44m XYZ \u001b[m\u001b[1;36;45m XYZ \u001b[m\u001b[1;36;46m XYZ \u001b[m\u001b[1;36;47m XYZ \u001b[m\n",
" 37 \u001b[37m XYZ \u001b[m\u001b[37;40m XYZ \u001b[m\u001b[37;41m XYZ \u001b[m\u001b[37;42m XYZ \u001b[m\u001b[37;43m XYZ \u001b[m\u001b[37;44m XYZ \u001b[m\u001b[37;45m XYZ \u001b[m\u001b[37;46m XYZ \u001b[m\u001b[37;47m XYZ \u001b[m\n",
" 1;37 \u001b[1;37m XYZ \u001b[m\u001b[1;37;40m XYZ \u001b[m\u001b[1;37;41m XYZ \u001b[m\u001b[1;37;42m XYZ \u001b[m\u001b[1;37;43m XYZ \u001b[m\u001b[1;37;44m XYZ \u001b[m\u001b[1;37;45m XYZ \u001b[m\u001b[1;37;46m XYZ \u001b[m\u001b[1;37;47m XYZ \u001b[m\n"
]
}
],
"source": [
"text = \" XYZ \"\n",
"formatstring = \"\\x1b[{}m\" + text + \"\\x1b[m\"\n",
"\n",
"print(\n",
" \" \" * 6\n",
" + \" \" * len(text)\n",
" + \"\".join(\"{:^{}}\".format(bg, len(text)) for bg in range(40, 48))\n",
")\n",
"for fg in range(30, 38):\n",
" for bold in False, True:\n",
" fg_code = (\"1;\" if bold else \"\") + str(fg)\n",
" print(\n",
" \" {:>4} \".format(fg_code)\n",
" + formatstring.format(fg_code)\n",
" + \"\".join(\n",
" formatstring.format(fg_code + \";\" + str(bg)) for bg in range(40, 48)\n",
" )\n",
" )"
]
},
{
"cell_type": "markdown",
"id": "8c3ce605",
"metadata": {},
"source": [
":::{note}\n",
"ANSI also supports a set of 256 indexed colors.\n",
"This is currently not supported, but we hope to introduce it at a later date\n",
"(raise an issue on the repository if you require it!).\n",
":::\n",
"\n",
"(render/output/cutomise)=\n",
"## Customise the render process\n",
"\n",
"The render process is governed by subclasses of {py:class}`~myst_nb.core.render.NbElementRenderer`, which dictate how to create the `docutils` AST nodes for elements of the notebook.\n",
"\n",
"Implementations are loaded *via* Python [entry points](https://packaging.python.org/guides/distributing-packages-using-setuptools/#entry-points), in the `myst_nb.renderers` group.\n",
"So it is possible to inject your own subclass to fully override rendering.\n",
"\n",
"For example, the renderer loaded in this package is:\n",
"\n",
"```toml\n",
"[project.entry-points.\"myst_nb.renderers\"]\n",
"default = \"myst_nb.core.render:NbElementRenderer\"\n",
"```\n",
"\n",
"You can then select the renderer plugin in your `conf.py`:\n",
"\n",
"```python\n",
"nb_render_plugin = \"default\"\n",
"```\n",
"\n",
"Plugins can also override rendering of particular output MIME types,\n",
"using the `myst_nb.mime_renderers` entry point group to supply functions with signature: {py:class}`~myst_nb.core.render.MimeRenderPlugin`.\n",
"\n",
"For example {py:class}`myst_nb.core.render.ExampleMimeRenderPlugin`, is loaded in this package:\n",
"\n",
"```toml\n",
"[project.entry-points.\"myst_nb.mime_renderers\"]\n",
"example = \"myst_nb.core.render:ExampleMimeRenderPlugin\"\n",
"```\n",
"\n",
"Meaning we can now render `custommimetype` in all output formats:"
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "81479674",
"metadata": {},
"outputs": [
{
"data": {
"custommimetype": "Some text"
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"from IPython.display import display\n",
"display({\"custommimetype\": \"Some text\"}, raw=True)"
]
}
],
"metadata": {
"file_format": "mystnb",
"kernelspec": {
"display_name": "python3",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.6"
},
"source_map": [
5,
33,
41,
66,
74,
109,
115,
184,
200,
222,
234,
248,
251,
255,
257,
287,
303,
310,
315,
329,
348,
389
]
},
"nbformat": 4,
"nbformat_minor": 5
}