{ "cells": [ { "cell_type": "markdown", "id": "06adc052", "metadata": {}, "source": [ "(render/eval)=\n", "\n", "# Inline variable evaluation (eval)\n", "\n", "```{versionadded} 0.15.0\n", "```\n", "\n", "The `eval` submodule allows you to insert code variables directly into the text flow of your documentation.\n", "\n", "Use of `eval` requires that the [notebook execution mode](execute/modes) is set to `inline`, since the variables are evaluated by the notebook kernel.\n", "For example, using the [top-matter](authoring/text-notebooks):\n", "\n", "```yaml\n", "---\n", "file_format: mystnb\n", "kernelspec:\n", " name: python3\n", "mystnb:\n", " execution_mode: 'inline'\n", "---\n", "```\n", "\n", "## Basic example\n", "\n", "Below we set a variable `v1` within a code cell." ] }, { "cell_type": "code", "execution_count": 1, "id": "563b5b75", "metadata": {}, "outputs": [], "source": [ "v1 = \"My variable\"" ] }, { "cell_type": "markdown", "id": "e9fcbdd6", "metadata": {}, "source": [ "Using the `eval` role, we can insert the variable `v1` into the text of a paragraph:\n", "\n", "`` {eval}`v1` `` -> {eval}`v1`\n", "\n", "If we update the variable, we can see the change reflected in subsequent evaluation:" ] }, { "cell_type": "code", "execution_count": 2, "id": "bf08363e", "metadata": {}, "outputs": [], "source": [ "v1 = \"My new variable\"" ] }, { "cell_type": "markdown", "id": "8a02284f", "metadata": {}, "source": [ "`` {eval}`v1` `` -> {eval}`v1`\n", "\n", ":::{important}\n", "Variable names must match the regex `[a-zA-Z][a-zA-Z0-9_]*`\n", ":::\n", "\n", "## Inserting different output types\n", "\n", "Any variable type can be inserted into the text flow using the `eval` role,\n", "and the most suitable output type will be used, based on the output format (see {ref}`render/output/priority` for more information).\n", "For example:" ] }, { "cell_type": "code", "execution_count": 3, "id": "231e0713", "metadata": {}, "outputs": [], "source": [ "import ipywidgets as widgets\n", "slider = widgets.IntSlider(value=5, min=0, max=10)" ] }, { "cell_type": "markdown", "id": "e8af4be1", "metadata": {}, "source": [ "An inline slider (`` {eval}`slider` ``): {eval}`slider`\n", "\n", "You can also use the `eval` directive to insert variables as blocks:" ] }, { "cell_type": "code", "execution_count": 4, "id": "2bb99812", "metadata": {}, "outputs": [], "source": [ "import matplotlib.pyplot as plt\n", "myplot, ax = plt.subplots(figsize=(6, 2))\n", "mean = 2.0\n", "ax.plot([1,2,3])\n", "ax.grid()\n", "plt.close()" ] }, { "cell_type": "markdown", "id": "3443b19d", "metadata": {}, "source": [ "using:\n", "\n", "````markdown\n", "```{eval} myplot\n", "```\n", "````\n", "\n", "gives:\n", "\n", "```{eval} myplot\n", "```\n", "\n", "## Embedding outputs in figures\n", "\n", "The `eval:figure` directive allows you to embed outputs in a figure,\n", "with an optional caption and other formatting options.\n", "\n", "For example, we can embed the output of the above plot in a figure:\n", "\n", "`````markdown\n", "```{eval:figure} myplot\n", ":name: myplot\n", "My plot with a mean value of {eval}`mean`.\n", "```\n", "`````\n", "\n", "which gives:\n", "\n", "```{eval:figure} myplot\n", ":name: myplot\n", "My plot with a mean value of {eval}`mean`.\n", "```\n", "\n", "That can be referenced with `` {ref}`myplot` ``: {ref}`myplot`\n", "\n", "The following directive options are available:\n", "\n", ":::{table} `eval:figure` directive options\n", "| Option | Type | Description |\n", "| ------ | ---- | ----------- |\n", "| figwidth | length or percentage | The width of the figure |\n", "| figclass | text | A space-separated list of class names for the figure |\n", "| name | text | referenceable label for the figure |\n", "| alt | text | Alternate text of an image |\n", "| height | length | The desired height of an image |\n", "| width | length or percentage | The width of an image |\n", "| scale | percentage | The uniform scaling factor of an image |\n", "| class | text | A space-separated list of class names for the image |\n", "| align | text | left, center, or right |\n", ":::" ] } ], "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" }, "mystnb": { "execution_mode": "inline" }, "source_map": [ 7, 35, 37, 45, 47, 61, 64, 70, 77 ], "widgets": { "application/vnd.jupyter.widget-state+json": { "state": { "00858d998d724b06aab5c9ff6e2232cc": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "SliderStyleModel", "state": { "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "SliderStyleModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "StyleView", "description_width": "", "handle_color": null } }, "5e8652d259e84cca989c09e0b009a3cb": { "model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "IntSliderModel", "state": { "_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "IntSliderModel", "_view_count": null, "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", "_view_name": "IntSliderView", "behavior": "drag-tap", "continuous_update": true, "description": "", "description_allow_html": false, "disabled": false, "layout": "IPY_MODEL_81afc1fe79d449699ac9ca753ed1b515", "max": 10, "min": 0, "orientation": "horizontal", "readout": true, "readout_format": "d", "step": 1, "style": "IPY_MODEL_00858d998d724b06aab5c9ff6e2232cc", "tabbable": null, "tooltip": null, "value": 5 } }, "81afc1fe79d449699ac9ca753ed1b515": { "model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", "state": { "_model_module": "@jupyter-widgets/base", "_model_module_version": "2.0.0", "_model_name": "LayoutModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "LayoutView", "align_content": null, "align_items": null, "align_self": null, "border_bottom": null, "border_left": null, "border_right": null, "border_top": null, "bottom": null, "display": null, "flex": null, "flex_flow": null, "grid_area": null, "grid_auto_columns": null, "grid_auto_flow": null, "grid_auto_rows": null, "grid_column": null, "grid_gap": null, "grid_row": null, "grid_template_areas": null, "grid_template_columns": null, "grid_template_rows": null, "height": null, "justify_content": null, "justify_items": null, "left": null, "margin": null, "max_height": null, "max_width": null, "min_height": null, "min_width": null, "object_fit": null, "object_position": null, "order": null, "overflow": null, "padding": null, "right": null, "top": null, "visibility": null, "width": null } } }, "version_major": 2, "version_minor": 0 } } }, "nbformat": 4, "nbformat_minor": 5 }