{ "cells": [ { "cell_type": "markdown", "id": "9ab80dfa", "metadata": {}, "source": [ "(authoring/jupyter-notebooks)=\n", "# Jupyter Notebooks\n", "\n", "This notebook is a demonstration of directly-parsing Jupyter Notebooks into\n", "Sphinx using the MyST parser.[^download]\n", "\n", "[^download]: This notebook can be downloaded as **{nb-download}`jupyter-notebooks.ipynb`** and {download}`jupyter-notebooks.md`\n", "\n", "## Markdown\n", "\n", ":::{seealso}\n", "For more information about what you can write with MyST Markdown, see the\n", "[MyST Parser documentation](inv:myst#intro/get-started).\n", ":::\n", "\n", "### Configuration\n", "\n", "The MyST-NB parser derives from [the base MyST-Parser](inv:myst#intro/get-started), and so all the same configuration options are available.\n", "See the [MyST configuration options](inv:myst#sphinx/config-options) for the full set of options, and [MyST syntax guide](inv:myst#syntax/core) for all the syntax options.\n", "\n", "To build documentation from this notebook, the following options are set:\n", "\n", "```python\n", "myst_enable_extensions = [\n", " \"amsmath\",\n", " \"colon_fence\",\n", " \"deflist\",\n", " \"dollarmath\",\n", " \"html_image\",\n", "]\n", "myst_url_schemes = (\"http\", \"https\", \"mailto\")\n", "```\n", "\n", ":::{note}\n", "Loading the `myst_nb` extension also activates the [`myst_parser`](inv:myst#index) extension, for enabling the MyST flavour of Markdown.\n", "It is not required to add this explicitly in the list of `extensions`.\n", ":::\n", "\n", "### Syntax\n", "\n", "As you can see, markdown is parsed as expected. Embedding images should work as expected.\n", "For example, here's the MyST-NB logo:\n", "\n", "```md\n", "![myst-nb logo](../_static/logo-wide.svg)\n", "```\n", "\n", "![myst-nb logo](../_static/logo-wide.svg)\n", "\n", "By adding `\"html_image\"` to the `myst_enable_extensions` list in the sphinx configuration ([see here](inv:myst#syntax/images)), you can even add HTML `img` tags with attributes:\n", "\n", "```html\n", "\n", "```\n", "\n", "\n", "\n", "Because MyST-NB is using the MyST-markdown parser, you can include rich markdown with Sphinx in your notebook.\n", "For example, here's a note admonition block:\n", "\n", ":::::{note}\n", "**Wow**, a note!\n", "It was generated with this code ([as explained here](inv:myst:std:label#syntax/admonitions)):\n", "\n", "````md\n", ":::{note}\n", "**Wow**, a note!\n", ":::\n", "````\n", "\n", ":::::\n", "\n", "If you wish to use \"bare\" LaTeX equations, then you should add `\"amsmath\"` to the `myst_enable_extensions` list in the sphinx configuration.\n", "This is [explained here](inv:myst:std:label#syntax/amsmath), and works as such:\n", "\n", "```latex\n", "\\begin{equation}\n", "\\frac {\\partial u}{\\partial x} + \\frac{\\partial v}{\\partial y} = - \\, \\frac{\\partial w}{\\partial z}\n", "\\end{equation}\n", "\n", "\\begin{align*}\n", "2x - 5y &= 8 \\\\\n", "3x + 9y &= -12\n", "\\end{align*}\n", "```\n", "\n", "\\begin{equation}\n", "\\frac {\\partial u}{\\partial x} + \\frac{\\partial v}{\\partial y} = - \\, \\frac{\\partial w}{\\partial z}\n", "\\end{equation}\n", "\n", "\\begin{align*}\n", "2x - 5y &= 8 \\\\\n", "3x + 9y &= -12\n", "\\end{align*}\n", "\n", "Also you can use features like **equation numbering** and referencing in the notebooks:\n", "\n", "```md\n", "$$e^{i\\pi} + 1 = 0$$ (euler)\n", "```\n", "\n", "$$e^{i\\pi} + 1 = 0$$ (euler)\n", "\n", "Euler's identity, equation {math:numref}`euler`, was elected one of the\n", "most beautiful mathematical formulas.\n", "\n", "You can see the syntax used for this example [here in the MyST documentation](inv:myst:std:label#syntax/math).\n", "\n", "## Code cells and outputs\n", "\n", "You can run cells, and the cell outputs will be captured and inserted into\n", "the resulting Sphinx site.\n", "\n", "### `__repr__` and HTML outputs\n", "\n", "For example, here's some simple Python:" ] }, { "cell_type": "code", "execution_count": 1, "id": "46258793", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "array([[16.38361205, 43.25008905, 83.96798352, 66.52710727, 59.99049748,\n", " 5.98080802, 17.98264829, 68.91089537, 2.44428804, 78.89780567],\n", " [27.03775937, 18.13224755, 7.83031399, 12.2255668 , 85.50387032,\n", " 52.02698103, 76.2019338 , 39.40699111, 95.24408919, 12.0605026 ],\n", " [70.25294844, 87.24935759, 59.10211837, 12.53972441, 84.8256109 ,\n", " 77.98800178, 2.10093803, 83.44693849, 14.93454353, 45.60704253]])" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import matplotlib.pyplot as plt\n", "import numpy as np\n", "data = np.random.rand(3, 100) * 100\n", "data[:, :10]" ] }, { "cell_type": "markdown", "id": "7f618b41", "metadata": {}, "source": [ "This will also work with HTML outputs" ] }, { "cell_type": "code", "execution_count": 2, "id": "b9bfa9a0", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", " | a | \n", "b | \n", "c | \n", "
---|---|---|---|
0 | \n", "16.383612 | \n", "27.037759 | \n", "70.252948 | \n", "
1 | \n", "43.250089 | \n", "18.132248 | \n", "87.249358 | \n", "
2 | \n", "83.967984 | \n", "7.830314 | \n", "59.102118 | \n", "
3 | \n", "66.527107 | \n", "12.225567 | \n", "12.539724 | \n", "
4 | \n", "59.990497 | \n", "85.503870 | \n", "84.825611 | \n", "