{ "cells": [ { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ ".. _nbsphinx:\n\n", "nbsphinx\n", "========\n", "\n", "``nbsphinx`` is a Sphinx extension that provides a source parser for ``*.ipynb`` files.\n", "\n", "- **Documentation**: https://nbsphinx.readthedocs.io/\n", "- **Source Code**: https://github.com/spatialaudio/nbsphinx\n" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Install\n", "-------\n", "\n", ".. code-block:: bash\n", "\n", " pip install nbsphinx\n", "\n", "Then, add the extension to your ``conf.py``:\n", "\n", ".. code-block:: python\n", " :caption: conf.py\n", "\n", " extensions = [\n", " # ...\n", " \"nbsphinx\",\n", " ]\n" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Examples\n", "--------\n", "Here are some examples to show how nbsphinx rendering ``ipynb`` files." ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Code, Output, Streams\n", "~~~~~~~~~~~~~~~~~~~~~\n", "\n", "An empty code cell:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Two empty lines:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Leading/trailing empty lines:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# 2 empty lines before, 1 after\n" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "A simple output:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "6 * 7" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "The standard output stream:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(\"Hello, world!\")" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Normal output + standard output" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(\"Hello, world!\")\n", "6 * 7" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "The standard error stream is highlighted and displayed just below the code cell.\n", "The standard output stream comes afterwards (with no special highlighting).\n", "Finally, the \"normal\" output is displayed." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import sys\n", "\n", "print(\"I'll appear on the standard error stream\", file=sys.stderr)\n", "print(\"I'll appear on the standard output stream\")\n", "\"I'm the 'normal' output\"" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ ".. note::\n", "\n", " Using the IPython kernel, the order is actually mixed up,\n", " see https://github.com/ipython/ipykernel/issues/280.\n", "\n" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Math\n", "~~~~\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from IPython.display import Math\n", "\n", "eq = Math(r\"\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\")\n", "eq" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "display(eq)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from IPython.display import Latex\n", "\n", "Latex(r\"This is a \\LaTeX{} equation: $a^2 + b^2 = c^2$\")" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "%%latex\n", "\\begin{equation}\n", "\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n", "\\end{equation}" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "matplotlib\n", "~~~~~~~~~~~~~~\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import matplotlib.pyplot as plt\n", "import numpy as np\n", "\n", "fig, ax = plt.subplots(figsize=[6, 3])\n", "x = np.linspace(-5, 5, 50)\n", "ax.plot(x, np.sinc(x));" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "YouTube Videos\n", "~~~~~~~~~~~~~~\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from IPython.display import YouTubeVideo\n", "\n", "YouTubeVideo(\"9_OIs49m56E\")" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Tables\n", "~~~~~~\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import pandas as pd\n", "\n", "data = [[1, 2], [3, 4]]\n", "pd.DataFrame(data, columns=[\"Foo\", \"Bar\"])" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "ANSI Colors\n", "~~~~~~~~~~~\n", "\n", "The standard output and standard error streams may contain ", "`ANSI escape sequences `_ ", "to change the text and background colors." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(\"BEWARE: \\x1b[1;33;41mugly colors\\x1b[m!\", file=sys.stderr)\n", "print(\"AB\\x1b[43mCD\\x1b[35mEF\\x1b[1mGH\\x1b[4mIJ\\x1b[7mKL\\x1b[49mMN\\x1b[39mOP\\x1b[22mQR\\x1b[24mST\\x1b[27mUV\")" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "text = \" XYZ \"\n", "formatstring = \"\\x1b[{}m\" + text + \"\\x1b[m\"\n", "\n", "print(\" \" * 6 + \" \" * len(text) + \"\".join(\"{:^{}}\".format(bg, len(text)) for bg in range(40, 48)))\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(formatstring.format(fg_code + \";\" + str(bg)) for bg in range(40, 48))\n", " )" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "formatstring = \"\\x1b[38;5;{0};48;5;{0}mX\\x1b[1mX\\x1b[m\"\n", "\n", "print(\" + \" + \"\".join(\"{:2}\".format(i) for i in range(36)))\n", "print(\" 0 \" + \"\".join(formatstring.format(i) for i in range(16)))\n", "for i in range(7):\n", " i = i * 36 + 16\n", " print(\"{:3} \".format(i) + \"\".join(formatstring.format(i + j) for j in range(36) if i + j < 256))" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "start = 255, 0, 0\n", "end = 0, 0, 255\n", "length = 79\n", "out = []\n", "\n", "for i in range(length):\n", " rgb = [start[c] + int(i * (end[c] - start[c]) / length) for c in range(3)]\n", " out.append(\"\\x1b[38;2;{rgb[2]};{rgb[1]};{rgb[0]};48;2;{rgb[0]};{rgb[1]};{rgb[2]}mX\\x1b[m\".format(rgb=rgb))\n", "print(\"\".join(out))" ] }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ ".. hint::\n", "\n", " This documentation itself is written in ``.ipynb``. To view the source code,\n", " click the **Edit this page** link on the right sidebar." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "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.4.4" } }, "nbformat": 4, "nbformat_minor": 0 }