| 1 |
{ |
| 2 |
"cells": [ |
| 3 |
{ |
| 4 |
"cell_type": "code", |
| 5 |
"execution_count": null, |
| 6 |
"metadata": {}, |
| 7 |
"outputs": [], |
| 8 |
"source": [ |
| 9 |
"%matplotlib inline" |
| 10 |
] |
| 11 |
}, |
| 12 |
{ |
| 13 |
"cell_type": "markdown", |
| 14 |
"metadata": { |
| 15 |
"cell_marker": "\"\"\"" |
| 16 |
}, |
| 17 |
"source": [ |
| 18 |
"Notebook styled examples\n", |
| 19 |
"========================\n", |
| 20 |
"\n", |
| 21 |
"The gallery is capable of transforming Python files into reStructuredText files\n", |
| 22 |
"with a notebook structure. For this to be used you need to respect some syntax\n", |
| 23 |
"rules.\n", |
| 24 |
"\n", |
| 25 |
"It makes a lot of sense to contrast this output rst file with the\n", |
| 26 |
":download:`original Python script <plot_notebook.py>` to get better feeling of\n", |
| 27 |
"the necessary file structure.\n", |
| 28 |
"\n", |
| 29 |
"Anything before the Python script docstring is ignored by sphinx-gallery and\n", |
| 30 |
"will not appear in the rst file, nor will it be executed.\n", |
| 31 |
"This Python docstring requires an reStructuredText title to name the file and\n", |
| 32 |
"correctly build the reference links.\n", |
| 33 |
"\n", |
| 34 |
"Once you close the docstring you would be writing Python code. This code gets\n", |
| 35 |
"executed by sphinx gallery shows the plots and attaches the generating code.\n", |
| 36 |
"Nevertheless you can break your code into blocks and give the rendered file\n", |
| 37 |
"a notebook style. In this case you have to include a code comment breaker\n", |
| 38 |
"a line of at least 20 hashes and then every comment start with the a new hash.\n", |
| 39 |
"\n", |
| 40 |
"As in this example we start by first writing this module\n", |
| 41 |
"style docstring, then for the first code block we write the example file author\n", |
| 42 |
"and script license continued by the import modules instructions.\n", |
| 43 |
"\n", |
| 44 |
"Original script from:\n", |
| 45 |
"https://sphinx-gallery.readthedocs.io/en/latest/tutorials/plot_notebook.html" |
| 46 |
] |
| 47 |
}, |
| 48 |
{ |
| 49 |
"cell_type": "code", |
| 50 |
"execution_count": null, |
| 51 |
"metadata": {}, |
| 52 |
"outputs": [], |
| 53 |
"source": [ |
| 54 |
"# Code source: Óscar Nájera\n", |
| 55 |
"# License: BSD 3 clause\n", |
| 56 |
"\n", |
| 57 |
"import numpy as np\n", |
| 58 |
"import matplotlib.pyplot as plt" |
| 59 |
] |
| 60 |
}, |
| 61 |
{ |
| 62 |
"cell_type": "markdown", |
| 63 |
"metadata": { |
| 64 |
"cell_marker": "##############################################################################" |
| 65 |
}, |
| 66 |
"source": [ |
| 67 |
"This code block is executed, although it produces no output. Lines starting\n", |
| 68 |
"with a simple hash are code comment and get treated as part of the code\n", |
| 69 |
"block. To include this new comment string we started the new block with a\n", |
| 70 |
"long line of hashes.\n", |
| 71 |
"\n", |
| 72 |
"The sphinx-gallery parser will assume everything after this splitter and that\n", |
| 73 |
"continues to start with a **comment hash and space** (respecting code style)\n", |
| 74 |
"is text that has to be rendered in\n", |
| 75 |
"html format. Keep in mind to always keep your comments always together by\n", |
| 76 |
"comment hashes. That means to break a paragraph you still need to comment\n", |
| 77 |
"that line break.\n", |
| 78 |
"\n", |
| 79 |
"In this example the next block of code produces some plotable data. Code is\n", |
| 80 |
"executed, figure is saved and then code is presented next, followed by the\n", |
| 81 |
"inlined figure." |
| 82 |
] |
| 83 |
}, |
| 84 |
{ |
| 85 |
"cell_type": "code", |
| 86 |
"execution_count": null, |
| 87 |
"metadata": {}, |
| 88 |
"outputs": [], |
| 89 |
"source": [ |
| 90 |
"x = np.linspace(-np.pi, np.pi, 300)\n", |
| 91 |
"xx, yy = np.meshgrid(x, x)\n", |
| 92 |
"z = np.cos(xx) + np.cos(yy)\n", |
| 93 |
"\n", |
| 94 |
"plt.figure()\n", |
| 95 |
"plt.imshow(z)\n", |
| 96 |
"plt.colorbar()\n", |
| 97 |
"plt.xlabel('$x$')\n", |
| 98 |
"plt.ylabel('$y$')" |
| 99 |
] |
| 100 |
}, |
| 101 |
{ |
| 102 |
"cell_type": "markdown", |
| 103 |
"metadata": { |
| 104 |
"cell_marker": "###########################################################################" |
| 105 |
}, |
| 106 |
"source": [ |
| 107 |
"Again it is possible to continue the discussion with a new Python string. This\n", |
| 108 |
"time to introduce the next code block generates 2 separate figures." |
| 109 |
] |
| 110 |
}, |
| 111 |
{ |
| 112 |
"cell_type": "code", |
| 113 |
"execution_count": null, |
| 114 |
"metadata": {}, |
| 115 |
"outputs": [], |
| 116 |
"source": [ |
| 117 |
"plt.figure()\n", |
| 118 |
"plt.imshow(z, cmap=plt.cm.get_cmap('hot'))\n", |
| 119 |
"plt.figure()\n", |
| 120 |
"plt.imshow(z, cmap=plt.cm.get_cmap('Spectral'), interpolation='none')" |
| 121 |
] |
| 122 |
}, |
| 123 |
{ |
| 124 |
"cell_type": "markdown", |
| 125 |
"metadata": { |
| 126 |
"cell_marker": "##########################################################################" |
| 127 |
}, |
| 128 |
"source": [ |
| 129 |
"There's some subtle differences between rendered html rendered comment\n", |
| 130 |
"strings and code comment strings which I'll demonstrate below. (Some of this\n", |
| 131 |
"only makes sense if you look at the\n", |
| 132 |
":download:`raw Python script <plot_notebook.py>`)\n", |
| 133 |
"\n", |
| 134 |
"Comments in comment blocks remain nested in the text." |
| 135 |
] |
| 136 |
}, |
| 137 |
{ |
| 138 |
"cell_type": "code", |
| 139 |
"execution_count": null, |
| 140 |
"metadata": {}, |
| 141 |
"outputs": [], |
| 142 |
"source": [ |
| 143 |
"\n", |
| 144 |
"def dummy():\n", |
| 145 |
" \"\"\"Dummy function to make sure docstrings don't get rendered as text\"\"\"\n", |
| 146 |
" pass\n", |
| 147 |
"\n", |
| 148 |
"# Code comments not preceded by the hash splitter are left in code blocks.\n", |
| 149 |
"\n", |
| 150 |
"string = \"\"\"\n", |
| 151 |
"Triple-quoted string which tries to break parser but doesn't.\n", |
| 152 |
"\"\"\"" |
| 153 |
] |
| 154 |
}, |
| 155 |
{ |
| 156 |
"cell_type": "markdown", |
| 157 |
"metadata": { |
| 158 |
"cell_marker": "############################################################################" |
| 159 |
}, |
| 160 |
"source": [ |
| 161 |
"Output of the script is captured:" |
| 162 |
] |
| 163 |
}, |
| 164 |
{ |
| 165 |
"cell_type": "code", |
| 166 |
"execution_count": null, |
| 167 |
"metadata": {}, |
| 168 |
"outputs": [], |
| 169 |
"source": [ |
| 170 |
"print('Some output from Python')" |
| 171 |
] |
| 172 |
}, |
| 173 |
{ |
| 174 |
"cell_type": "markdown", |
| 175 |
"metadata": { |
| 176 |
"cell_marker": "############################################################################" |
| 177 |
}, |
| 178 |
"source": [ |
| 179 |
"Finally, I'll call ``show`` at the end just so someone running the Python\n", |
| 180 |
"code directly will see the plots; this is not necessary for creating the docs" |
| 181 |
] |
| 182 |
}, |
| 183 |
{ |
| 184 |
"cell_type": "code", |
| 185 |
"execution_count": null, |
| 186 |
"metadata": {}, |
| 187 |
"outputs": [], |
| 188 |
"source": [ |
| 189 |
"plt.show()" |
| 190 |
] |
| 191 |
}, |
| 192 |
{ |
| 193 |
"cell_type": "markdown", |
| 194 |
"metadata": { |
| 195 |
"cell_marker": "############################################################################" |
| 196 |
}, |
| 197 |
"source": [ |
| 198 |
"You can also include :math:`math` inline, or as separate equations:\n", |
| 199 |
"\n", |
| 200 |
".. math::\n", |
| 201 |
"\n", |
| 202 |
" \\exp(j\\pi) = -1\n", |
| 203 |
"\n", |
| 204 |
"You can also insert images:\n", |
| 205 |
"\n", |
| 206 |
".. image:: http://www.sphinx-doc.org/en/stable/_static/sphinxheader.png\n", |
| 207 |
" :alt: Sphinx header\n" |
| 208 |
] |
| 209 |
} |
| 210 |
], |
| 211 |
"metadata": { |
| 212 |
"jupytext": { |
| 213 |
"cell_metadata_filter": "-all", |
| 214 |
"encoding": "# -*- coding: utf-8 -*-", |
| 215 |
"main_language": "python", |
| 216 |
"notebook_metadata_filter": "-all" |
| 217 |
} |
| 218 |
}, |
| 219 |
"nbformat": 4, |
| 220 |
"nbformat_minor": 2 |
| 221 |
} |