docs/usage.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(myst-nb-usage)=\n",
    "# MyST-NB Usage\n",
    "\n",
    "The (probably) most useful function of this library is the `myst_nb_metadata_injector`.\n",
    "This allows you to write _magic-comments_ inside of your Jupyter code cells to inject metadata into those cells and configure the execution/rendering behavior of the  {{mystnb}} library.\n",
    "\n",
    "For example, with a simple comment like `# remove-input` you can remove the code cell in your rendered documentation and only show the output without having to fight with setting the metadata tags of your code cell. See the following example:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Source (what you would write inside of your Jupyter notebook)\n",
    "```python\n",
    "# remove-input\n",
    "print(\"My code cell is removed\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered output of MyST-NB:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove-input\n",
    "print(\"My code cell is removed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can (can't ?) see the output of the cell was rendered but the code-cell itself is hidden on the generated page."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The main motivation for this functionality is to keep the configuration _local_ and not hide it behind an `metadata` window inside of the Jupyter Notebook UI.\n",
    "This is especially frustrating for users that use UIs that do not support configuring the code cell metadata, like VSCode.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Enabling the Metadata Injector for MyST-NB\n",
    "\n",
    "To enable {{mystnb}} to use the metadata injection preprocessor by default, you have to add the following code to your [conf.py](https://www.sphinx-doc.org/en/master/usage/configuration.html):\n",
    "\n",
    "\n",
    "```{literalinclude} conf.py\n",
    "---\n",
    "language: python\n",
    "start-after: enable-start\n",
    "end-before: enable-end\n",
    "---\n",
    "```\n",
    "\n",
    "The current version requires _you_ to specify the `prefix` that indicates the start of a potential _magic comment_.\n",
    "Usually, this should be comment symbol(s) of the programming language.\n",
    "By default, and used in the example above, the `prefix=#` as this is the comment symbol for the Python programming language.\n",
    "The `delimiter` may be a character/string of your choice and will be used for separating key-value pairs.\n",
    "If you would like to add _additional_ [tags](sec/tags-conf) (when writing custom CSS rules, for example), you can also specify these as a list of strings in the `extra_tags` option.\n",
    "\n",
    "To see a list of all possible configuration, see the [API documentation of mystnb_nb_metadata_injector](myst_nb_metadata_injector).\n",
    "\n",
    ":::{important}\n",
    "To overwrite the default `ipynb` extension parser, you are required to use `MyST-NB>=0.14.0`!\n",
    "At the time of writing, the [jupyter-book project](https://jupyterbook.org/en/stable/intro.html) (`v0.13`) fixes the `MyST-NB` version to `0.13.1` and _cannot_ overwrite the default `ipynb` format.\n",
    "\n",
    "You can rename your notebooks with a different extension (only characters after the last `.` are considered the extension) and use that option for the custom parser instead.\n",
    "The main issue with that approach is that some tools have a hard time working with a different extension for Jupyter notebooks (like VSCode).\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Understanding the examples\n",
    "\n",
    "To show the _effects_ of the different options, the article will be structured as follows:\n",
    "\n",
    "1. The jupyter-notebook cell's source code is shown. The visual indicator of the _source_ code of the code cell, is that the stylized code-cell has _no_ border around it.\n",
    "2. The jupyter-notebook cell's source code is displayed _after_ applying the preprocessor. This will remove the magic comment and inject the metadata into the cell's code (not shown here). The processed code cell is stylized with a white border and a green left-border. This is the rendered code cell you would be seeing in your documentation.\n",
    "3. The output of the executed code-cell is shown with a white bordered cell.\n",
    "\n",
    "And one last visual example to clarify the different _stages_:\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# I am stage 1 and show the 'source' code of\n",
    "# the code cell\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# magic-comment\n",
    "\"\"\"\n",
    "I am stage 2 and show the post-processed code cell.\n",
    "If the magic comment matches one of the MyST-NB tags\n",
    "it would be removed from this cell and injected into the\n",
    "metadata field.\n",
    "\"\"\"\n",
    "print(\"I am the rendered code cell output\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The {{mystnb}} library provides two ways to configure the execution/rendering process of a code cell.\n",
    "One is to _add_ specific strings to the `tags` metadata list.\n",
    "See [](sec/tags-conf) for details on what is possible with this configuration method.\n",
    "The other configuration method is to _set_ key-value pairs inside of the `mystnb` metadata tag of the code-cell.\n",
    "See [](sec/mystnb-conf) for details.\n",
    "Note that the things you can configure are _mostly_ different between both of these methods! You should take a look at _both_!\n",
    "I've also spend quite a lot of time to create some _syntax_ sugar for settings nested key-value pairs. See [](sec/syntax_sugar) for more details.\n",
    "\n",
    "If the last paragraph confused you, don't worry.\n",
    "It is probably not that important for you as it discusses the _conceptual_ difference between the two configuration options.\n",
    "The important thing to know is that the `tag` based configuration only allows you to _add_ a string, while the other allows you to set a key-value pair.\n",
    "You will see how this effects the configuration in the following sections."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/tags-conf)=\n",
    "## Tag configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the time of writing, the following configuration keywords can be set in the `tags` metadata entry of a Jupyter code-cell:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- [](sec/remove-input)\n",
    "- [](sec/hide-input)\n",
    "- [](sec/remove-stderr)\n",
    "- [](sec/remove-output)\n",
    "- [](sec/hide-output)\n",
    "- [](sec/remove-cell)\n",
    "- [](sec/hide-cell)\n",
    "- [](sec/skip-execution)\n",
    "- [](sec/raises-exception)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more details, see the `Cell tags` section of the {external+mystnb:doc}`MyST configuration documentation <configuration>`.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### no-match example\n",
    "\n",
    "Example showing what happens with code cells that do _not_ include magic comments/are _normal_ code cells.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# unknown\n",
    "print(\"Example showing what happens if the cell doesn't include a magic comment\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# unknown\n",
    "print(\"Example showing what happens if the cell doesn't include a magic comment\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Not so surprisingly, nothing much happens with those code-cells. They are simply executed and rendered as-is."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/remove-input)=\n",
    "### remove-input"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Removes the source code of the cell.\n",
    "Useful if you are only interested in the output.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# remove-input\n",
    "print(\"My code cell is removed\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove-input\n",
    "print(\"My code cell is removed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/hide-input)=\n",
    "### hide-input\n",
    "\n",
    "Hide the source code of the cell behind a collapsible button.\n",
    "Useful if you want to draw the attention of the reader away from the code but still allow them to view the code if interested.\n",
    "\n",
    "Source:\n",
    "\n",
    "```python\n",
    "# hide-input\n",
    "print(\"My code cell is hidden behind a collapsible button.\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# hide-input\n",
    "print(\"My code cell is hidden behind a collapsible button.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/remove-stderr)=\n",
    "### remove-stderr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Only remove the standard error output of the code cell.\n",
    "This is useful if an underlying library uses `stderr` to print progress or other debug messages that would only pollute the output for the documentation.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# remove-stderr\n",
    "import sys\n",
    "print(\"The stderr output is removed\", file=sys.stderr)\n",
    "print(\"But not the default output\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove-stderr\n",
    "import sys\n",
    "\n",
    "print(\"The stderr output is removed\", file=sys.stderr)\n",
    "print(\"But not the default output\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/remove-output)=\n",
    "### remove-output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Remove the output of the code cell (duh).\n",
    "Useful to hide some warning during important without having filter the messages or to hide visual output.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# remove-output\n",
    "import sys\n",
    "print(\"My output is removed\")\n",
    "print(\"including the error output\", file=sys.stderr)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove-output\n",
    "import sys\n",
    "\n",
    "print(\"My output is removed\")\n",
    "print(\"including the error output\", file=sys.stderr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/hide-output)=\n",
    "### hide-output\n",
    "\n",
    "Hide the output of the code cell behind a collapsible button.\n",
    "This affects the entire output (`stderr` and `stdout`, like [](sec/remove-output)).\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# hide-output\n",
    "print(\"My output is hidden behind a collapsible button.\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# hide-output\n",
    "print(\"My output is hidden behind a collapsible button.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/remove-cell)=\n",
    "### remove-cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Remove the input as well as the output of the code cell.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# remove-cell\n",
    "print(\"This entire cell is removed\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove-cell\n",
    "print(\"This entire cell is removed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can (can't ?) see the cell is missing from the documentation page.\n",
    "\n",
    "```{note}\n",
    "The code-cell is still executed under the hood!\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/hide-cell)=\n",
    "### hide-cell\n",
    "\n",
    "Hide the input as well as the output of the code cell behind a collapsible button.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# hide-cell\n",
    "print(\"The input and output is hidden behind a collapsible button.\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# hide-cell\n",
    "print(\"The input and output is hidden behind a collapsible button.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/raises-exception)=\n",
    "### raises-exception\n",
    "\n",
    "The following code raises an exception and has \n",
    "`raises-exception` set to signal that the exception  is expected and continues with the execution and build process of the documentation.\n",
    "This is helpful, if you are showing examples of _failing_ code and want to include the trace-back.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# raises-exception\n",
    "1 / 0\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# raises-exception\n",
    "1 / 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/skip-execution)=\n",
    "### skip-execution\n",
    "\n",
    "The following code _would_ raise an exception but the execution of the cell is skipped and not exception is raised.\n",
    "\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# skip-execution\n",
    "1 / 0\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# skip-execution\n",
    "1 / 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice how no output is produced and no exception is raised."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/mystnb-conf)=\n",
    "## Myst-NB Metadata Configuration\n",
    "\n",
    "At the time of writing, the following configuration keyword-value pairs can be set in the `mystnb` metadata entry of a Jupyter code-cell:\n",
    "\n",
    "- [](sec/remove_code_source)\n",
    "- [](sec/remove_code_outputs)\n",
    "- [](sec/code_prompt_show)\n",
    "- [](sec/code_prompt_hide)\n",
    "- [](sec/number_source_lines)\n",
    "- [](sec/output_stderr)\n",
    "- [](sec/merge_streams)\n",
    "- [](sec/text_lexer)\n",
    "- [](sec/error_lexer)\n",
    "- [](sec/markdown_format)\n",
    "- [](sec/image)\n",
    "- [](sec/figure)\n",
    "\n",
    "\n",
    "In contrast to the `tag`-based configuration, the `mystnb`-based configuration uses a key-value pair!\n",
    "The `delimiter` is used to separate the key-value pairs.\n",
    "Note that spaces around the `delimiter` are allowed/ignored during the parsing process.\n",
    "The value is **parsed as a [yaml](https://en.wikipedia.org/wiki/YAML)-string**!\n",
    "This allows you to even set nested structures in a single line and is required for coercing the data to the correct type.\n",
    "\n",
    ":::{important}\n",
    "The value of the key-value pair is parsed as a _yaml_-string to allow correctly coercing the data to the desired type and to allow nested structures within a line.\n",
    "\n",
    "This library _only_ allows setting the value on the same line. This means that you _cannot_ write the value across multiple lines!\n",
    ":::\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/remove_code_source)=\n",
    "### remove_code_source\n",
    "\n",
    "Removes the code cell... (Surprising, right?)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Source:\n",
    "```python\n",
    "# remove_code_source = true\n",
    "print(\"My code cell is removed\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove_code_source = true\n",
    "print(\"My code cell is removed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/remove_code_outputs)=\n",
    "### remove_code_outputs\n",
    "\n",
    "Removes the output of the cell, including the output to standard error.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# remove_code_outputs = true\n",
    "import sys\n",
    "print(\"My output is removed\")\n",
    "print(\"including the error output\", file=sys.stderr)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove_code_outputs = true\n",
    "import sys\n",
    "\n",
    "print(\"My output is removed\")\n",
    "print(\"including the error output\", file=sys.stderr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/code_prompt_show)=\n",
    "### code_prompt_show\n",
    "Prompt _text_ that is displayed to inform the user that the dialog can be _expanded_.\n",
    "The optional `{type}` placeholder will be replaced with `content`, `source`, or `outputs`, depending on the `hide` tag ([](sec/hide-input), [](sec/hide-output), [](sec/hide-cell)).\n",
    "\n",
    ":::{note}\n",
    "Also requires the code cell to specify one of the `hide-X` options.\n",
    ":::\n",
    "\n",
    "Mainly included for completeness.\n",
    "This would be an ideal example of a configuration value that should be set globally instead of individually within each code cell.\n",
    "\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# hide-input\n",
    "# code_prompt_show = \"Click here to see my absolutely awesome {type}\"\n",
    "print(\"Setting code_prompt_show\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# hide-input\n",
    "# code_prompt_show = \"Click here to see my absolutely awesome {type}\"\n",
    "print(\"Setting code_prompt_show\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/code_prompt_hide)=\n",
    "### code_prompt_hide\n",
    "Prompt _text_ that is displayed to inform the user that the dialog can be _collapsed/minimized_.\n",
    "The optional `{type}` placeholder will be replaced with `content`, `source`, or `outputs`, depending on the `hide` tag ([](sec/hide-input), [](sec/hide-output), [](sec/hide-cell)).\n",
    "\n",
    ":::{note}\n",
    "Also requires the code cell to specify one of the `hide-X` options.\n",
    ":::\n",
    "\n",
    "Mainly included for completeness.\n",
    "This would be an ideal example of a configuration value that should be set globally instead of individually within each code cell.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# hide-input\n",
    "# code_prompt_hide = \"Click here to minimize my absolutely awesome {type} (What is wrong with it?! :( )\"\n",
    "print(\"Expand the button above to see the text!\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# hide-input\n",
    "# code_prompt_hide = \"Click here to minimize my awesome {type} (What is wrong with it?! 🥲)\"\n",
    "print(\"Expand the button above to see the hide prompt!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/number_source_lines)=\n",
    "### number_source_lines\n",
    "Add source line numbering to the current cell.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# number_source_lines = true\n",
    "# line 1\n",
    "# line 2\n",
    "print(\"I love my husky.\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# number_source_lines = true\n",
    "# line 1\n",
    "# line 2\n",
    "print(\"I love my husky.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/output_stderr)=\n",
    "### output_stderr\n",
    "\n",
    "Define the behavior for standard error output.\n",
    "Can be set to one of:\n",
    "- `show`: (Default) Show the stderr as a separate output\n",
    "- `remove`: Hide stderr\n",
    "- `remove-warn`: Hide stderr but log a warning to Sphinx\n",
    "- `warn|error|severe`: Log the error with a specific logging level to Sphinx"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Source:\n",
    "```python\n",
    "# output_stderr = show\n",
    "import sys\n",
    "print(\"stdout 0\")\n",
    "print(\"stderr\", file=sys.stderr)\n",
    "print(\"stdout 1\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# output_stderr = show\n",
    "import sys\n",
    "\n",
    "print(\"stdout 0\")\n",
    "print(\"stderr\", file=sys.stderr)\n",
    "print(\"stdout 1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Source:\n",
    "```python\n",
    "# output_stderr = remove\n",
    "import sys\n",
    "print(\"stdout 0\")\n",
    "print(\"stderr\", file=sys.stderr)\n",
    "print(\"stdout 1\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# output_stderr = remove\n",
    "import sys\n",
    "\n",
    "print(\"stdout 0\")\n",
    "print(\"stderr\", file=sys.stderr)\n",
    "print(\"stdout 1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the other options, see the official [MyST-NB documentation for the stderr configuration](https://myst-nb.readthedocs.io/en/latest/render/format_code_cells.html#remove-stdout-or-stderr)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/merge_streams)=\n",
    "### merge_streams\n",
    "\n",
    "Merge standard output and standard error into a single output cell.\n",
    "\n",
    ":::{error}\n",
    "This doesn't work!\n",
    "\n",
    "I will have to investigate why this isn't working.\n",
    "It seems like it also doesn't work by manually setting the tag.\n",
    ":::\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# merge_streams = true\n",
    "import sys\n",
    "print(\"stdout 0\")\n",
    "print(\"stderr\", file=sys.stderr)\n",
    "print(\"stdout 1\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "mystnb": {
     "merge_streams": true
    }
   },
   "outputs": [],
   "source": [
    "# merge_streams = true\n",
    "import sys\n",
    "\n",
    "print(\"stdout 0\")\n",
    "print(\"stderr\", file=sys.stderr)\n",
    "print(\"stdout 1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/text_lexer)=\n",
    "### text_lexer\n",
    "\n",
    "Pygments lexer applied to standard out, standard error and text/plain outputs.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# text_lexer = python\n",
    "print(\"# Render output with Python code cell lexer\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# text_lexer = python\n",
    "print(\"# Render output with Python code cell lexer\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/error_lexer)=\n",
    "### error_lexer\n",
    "Pygments lexer applied to the error/traceback outputs.\n",
    "Note, that to be able to correctly build the documentation, the following example also uses [](sec/raises-exception) to let the executor now that we _expect_ an exception to be raised.\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# error_lexer = python\n",
    "# raises-exception\n",
    "raise Exception(\"# The last line be lexed as a Python comment, everything else will be broken\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# error_lexer = python\n",
    "# raises-exception\n",
    "raise Exception(\n",
    "    \"# The last line be lexed as a Python comment, everything else will be broken\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/markdown_format)=\n",
    "### markdown_format\n",
    "The format to use for text/markdown rendering.\n",
    "\n",
    "Can be one of:\n",
    "- `commonmark` (Default)\n",
    "- `gfm`\n",
    "- `myst`\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# markdown_format = myst\n",
    "from IPython.display import Markdown\n",
    "\n",
    "Markdown(r\"\"\"\n",
    "Term 1\n",
    ": Requires `deflist` extension to be loaded\n",
    "\"\"\")\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# markdown_format = myst\n",
    "from IPython.display import Markdown\n",
    "\n",
    "Markdown(\n",
    "    r\"\"\"\n",
    "Term 1\n",
    ": Requires myst and `deflist` extension to be loaded\n",
    "\"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In contrast to the default with\n",
    "\n",
    "Source:\n",
    "```python\n",
    "# markdown_format = commonmark\n",
    "from IPython.display import Markdown\n",
    "\n",
    "Markdown(r\"\"\"\n",
    "Term 1\n",
    ": Won't render as `deflist` with commonmark\n",
    "\"\"\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# markdown_format = commonmark\n",
    "from IPython.display import Markdown\n",
    "\n",
    "Markdown(\n",
    "    r\"\"\"\n",
    "Term 1\n",
    ": Won't render as `deflist` with commonmark\n",
    "\"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/image)=\n",
    "### image\n",
    "\n",
    "Options for image outputs.\n",
    "\n",
    "To see a list of all possible configuration values, take a look at the [official image documentation](https://myst-nb.readthedocs.io/en/latest/render/format_code_cells.html#images-and-figures)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Source:\n",
    "\n",
    "```python\n",
    "# image = {\"width\": 20%, \"align\": \"right\", \"alt\": \"A cute comic-style fish with a party hat\"}\n",
    "from IPython.display import Image\n",
    "Image(\"fish.png\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# image = {\"width\": 20%, \"align\": \"right\", \"alt\": \"A cute comic-style fish with a party hat\"}\n",
    "from IPython.display import Image\n",
    "\n",
    "Image(\"fish.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/figure)=\n",
    "### figure\n",
    "\n",
    "Options for figure outputs.\n",
    "To see a list of all possible configuration values, take a look at the [official figure documentation](https://myst-nb.readthedocs.io/en/latest/render/format_code_cells.html#images-and-figures)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Source:\n",
    "\n",
    "```python\n",
    "# figure = {\"caption\": \"I am a top caption!\", \"caption_before\": true}\n",
    "from IPython.display import Image\n",
    "Image(\"fish.png\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# figure = {\"caption\": \"I am a top caption!\", \"caption_before\": true}\n",
    "from IPython.display import Image\n",
    "\n",
    "Image(\"fish.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(sec/syntax_sugar)=\n",
    "## Syntax Sugar\n",
    "\n",
    "I've spent _way too much time_ (and made the library significantly complexer) to allow nested key setting.\n",
    "This is especially useful for nested options such as [](sec/figure) and [](sec/image).\n",
    "So instead of writing a long line like the following:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Source:\n",
    "\n",
    "```python\n",
    "# figure = {\"caption\": \"I am a top caption!\", \"caption_before\": true}\n",
    "# image = {\"width\": \"10%\", \"alt\": \"Fish with party hat\"}\n",
    "from IPython.display import Image\n",
    "Image(\"fish.png\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# figure = {\"caption\": \"I am a top caption!\", \"caption_before\": true}\n",
    "# image = {\"width\": \"10%\", \"alt\": \"Fish with party hat\"}\n",
    "from IPython.display import Image\n",
    "\n",
    "Image(\"fish.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You could also write it in such a way that each option is on their own line and access the next _level_ with using the dot (`.`) character.\n",
    "\n",
    "```python\n",
    "# figure.caption = \"I am a top caption!\"\n",
    "# figure.caption_before = true\n",
    "# image.width = \"10%\"\n",
    "# image.alt = \"Fish with party hat\"\n",
    "from IPython.display import Image\n",
    "\n",
    "Image(\"fish.png\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# figure.caption = \"I am a top caption!\"\n",
    "# figure.caption_before = true\n",
    "# image.width = \"10%\"\n",
    "# image.alt = \"Fish with party hat\"\n",
    "from IPython.display import Image\n",
    "\n",
    "Image(\"fish.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.10 ('.venv': venv)",
   "language": "python",
   "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.9.10"
  },
  "vscode": {
   "interpreter": {
    "hash": "32e269cf0080e5d78d90d03fdac68272ba761dbfded2047b73ee17fa435bd3af"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}