diff --git a/HowTos/EmbedExternalResources/EmbedExternalResources.ipynb b/HowTos/EmbedExternalResources/EmbedExternalResources.ipynb
index e79744a..e45d681 100644
--- a/HowTos/EmbedExternalResources/EmbedExternalResources.ipynb
+++ b/HowTos/EmbedExternalResources/EmbedExternalResources.ipynb
@@ -1,460 +1,479 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Embed external resources in your notebook\n",
"\n",
"**What are external resources?**\n",
"\n",
"External resources are content/resources (videos, images, etc.) that are hosted on services other than Noto.\n",
"\n",
"**What is embeding?**\n",
"\n",
"Embeding is making this external content available from your notebooks, only by providing a reference (a URL, a Youtube video id, data). The external content does not need to be copied into the notebook or your repository.\n",
"\n",
"Note that, **in some cases**, the external content will be stored in the output cell of your notebook."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Introduction\n",
"\n",
- "In this section, we will demonstrate how to embed most commom contents in your notebooks ; most of these examples come from [this](http://louistiao.me/posts/demos/ipython-notebook-demo/) page.\n",
+ "In this section, we will demonstrate how to embed most commom contents in your notebooks using Python ; most of these examples come from [this](http://louistiao.me/posts/demos/ipython-notebook-demo/) page.\n",
"\n",
"## IPython's Rich Display System\n",
"\n",
"To render external content, we will use IPython (the library at the base of Jupyter kernels). In Python, objects can declare their textual representation using the `__repr__` method. IPython expands on this idea and allows objects to declare other, richer representations including:\n",
"\n",
"* HTML\n",
"* JSON\n",
"* PNG\n",
"* JPEG\n",
"* SVG\n",
"* $\\LaTeX$\n",
"\n",
"A single object can declare some or all of these representations; all are handled by IPython's display system. This Notebook shows how you can use this display system to incorporate a broad range of content into your Notebooks.\n",
"\n",
"# About the `display()` function\n",
"The `display()` function is a general purpose tool for displaying different representations of objects. Think of it as a `print()` fonction for these rich representations."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import display"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"A few points:\n",
"\n",
"* Calling `display()` on an object will send all possible representations to the Notebook.\n",
"* These representations are stored in the Notebook document (as part of the output cells).\n",
"* In general the Notebook will use the **richest** available representation.\n",
"\n",
"If you want to display a particular representation, there are specific functions for that:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import display_pretty, display_html, display_jpeg, display_png, display_json, display_latex, display_svg, display_pdf"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Examples\n",
"\n",
"Each example is self sufficient; you can just copy and reuse the content of each cell.\n",
"\n",
"## Videos\n",
"\n",
- "Embedding a remote video looks like that:"
+ "Embedding a remote video using Python code looks like that:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Video\n",
"Video('http://www.html5videoplayer.net/videos/toystory.mp4')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And this is a YouTube video, embedded via its video ID (`'IPrU6VsLl8c'`)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import YouTubeVideo\n",
"YouTubeVideo('IPrU6VsLl8c', 600, 337)"
]
},
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Of course, videos can also be embedded into Markdown cells using the HTML 5 tag: `` \n",
+ "\n",
+ "Which gives: \n",
+ "\n",
+ ""
+ ]
+ },
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Images\n",
"\n",
"JPEG and PNG images are supported."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Image\n",
"Image('https://upload.wikimedia.org/wikipedia/commons/c/c4/PM5544_with_non-PAL_signals.png', width=256, height=192)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You can also use SVG images - being vector graphics, your browser will extend the image as far as possible."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import SVG\n",
"SVG('https://upload.wikimedia.org/wikipedia/commons/f/fd/Ghostscript_Tiger.svg')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You can also set create an IFRAME (with a well define size) and let your browser render the SVG file :"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import IFrame\n",
"IFrame('https://upload.wikimedia.org/wikipedia/commons/f/fd/Ghostscript_Tiger.svg', 200, 200)"
]
},
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Of course, you can easily include images into Markdown cells, either using the Mardown syntax (see [the reference documentation](https://daringfireball.net/projects/markdown/basics)) or using the HTML syntax: \n",
+ "`![](\"https://upload.wikimedia.org/wikipedia/commons/4/4d/Periodic_table_large.svg\")
`"
+ ]
+ },
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Audio files and sound\n",
"\n",
"### Creating sound files"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Audio\n",
"import numpy as np\n",
"\n",
"# Mix two pure sines, 200 Hz and 202 Hz\n",
"framerate = 44100\n",
"t = np.linspace(0,5,framerate*5)\n",
"data = np.sin(2*np.pi*200*t) + np.sin(2*np.pi*202*t)\n",
"\n",
"# Show player - Check the resulting beat\n",
"Audio(data,rate=framerate)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Playing remote Audio files"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Audio\n",
"Audio('https://upload.wikimedia.org/wikipedia/commons/b/bb/Test_ogg_mp3_48kbps.wav')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Code\n",
"\n",
"While source code is basically text, it is best displayed using syntax coloring. There are two ways of doing this\n",
"\n",
"### Show the content of a local (or remote) file\n",
"\n",
"Using the `Code` class as shown below works with local and remote files written in many programming languages.. The `Code` class can detect the language (based on the filename extension) and adjust the coloring. In some situation you might have to specify explicitely the language of the contained code.\n",
"\n",
"This method will print in the output cell the **complete** file."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Code\n",
"Code('https://raw.githubusercontent.com/jupyterlab/jupyterlab-git/master/jupyterlab_git/__init__.py', language='python')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You can also display normal text as code, with the proper coloring:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Code\n",
"Code('print(\"hello\")', language='python')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Show selectively Python code (classes, methods, etc.)\n",
"\n",
"You can present to your readers external Python code by selectively presenting only the pieces you want using the `?` and `??` operators.\n",
"\n",
"Let's see the whole `MyLib` class:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from lib.mylib import MyLib\n",
"MyLib??"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now let's see only the **docstring** for this class:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from lib.mylib import MyLib\n",
"MyLib?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"What if you only want to show a single method of `MyLib` class? No problem!"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from lib.mylib import MyLib\n",
"MyLib.greet??"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from lib.mylib import MyLib\n",
"MyLib.greet?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note the importance of properly **documenting** your Python code: your documentation texts will pop right into the readers eyeballs when using the `??` and `?` operators."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Markdown, Maths and $\\LaTeX$\n",
"\n",
"### Simple Math text (rendered with MathJax)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Math\n",
"Math(r'F(k) = \\int_{-\\infty}^{\\infty} f(x) e^{2\\pi i k} dx')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### $\\LaTeX$ (equations and more)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Latex\n",
"Latex(r\"\"\"\\begin{eqnarray}\n",
"\\nabla \\times \\vec{\\mathbf{B}} -\\, \\frac1c\\, \\frac{\\partial\\vec{\\mathbf{E}}}{\\partial t} & = \\frac{4\\pi}{c}\\vec{\\mathbf{j}} \\\\\n",
"\\nabla \\cdot \\vec{\\mathbf{E}} & = 4 \\pi \\rho \\\\\n",
"\\nabla \\times \\vec{\\mathbf{E}}\\, +\\, \\frac1c\\, \\frac{\\partial\\vec{\\mathbf{B}}}{\\partial t} & = \\vec{\\mathbf{0}} \\\\\n",
"\\nabla \\cdot \\vec{\\mathbf{B}} & = 0 \n",
"\\end{eqnarray}\"\"\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Latex\n",
"Latex(r'To $\\infty$ and beyond!')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Markdown"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Markdown\n",
"Markdown('This is markdown text.\\n\\n* Some **more** markdown...\\n* This is a [greek](https://en.wikipedia.org/wiki/Greek) letter: $\\phi$')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## External HTML page (in an IFRAME)\n",
"\n",
"In the next example, an **IFRAME** is created in the output cell, showing you the complete documentation of the **IPython Display** module."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import IFrame\n",
"IFrame('https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html', 1024, 400)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## External PDF file (in an IFRAME)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import IFrame\n",
"IFrame('https://rogerdudler.github.io/git-guide/files/git_cheat_sheet.pdf', 1024, 800)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### End of notebook"
]
}
],
"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.6.8"
}
},
"nbformat": 4,
"nbformat_minor": 2
}
diff --git a/HowTos/OrganizeCode/OrganizeCode.ipynb b/HowTos/OrganizeCode/OrganizeCode.ipynb
index ffc6caf..0f11e9b 100644
--- a/HowTos/OrganizeCode/OrganizeCode.ipynb
+++ b/HowTos/OrganizeCode/OrganizeCode.ipynb
@@ -1,229 +1,226 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# How to organize your code in your notebooks?\n",
"\n",
"\n",
"\n",
- "It is important to have your notebooks as free as possible from Python code that is **not providing any useful information** for your students, or that adds **unecessary complexity** to your notebook. Sometimes, hidding some code in an external file is a nice solution.\n",
+ "In some cases, you might want to hide from your notebooks Python code that is **not providing any useful information** for your students, or that adds **unecessary complexity** to your content. Putting this code in an external file is a nice solution.\n",
"\n",
"This also helps separating the code in reusable bricks, for other notebooks. You can also use external Python files to put classes or functions in common, and reuse them in several notebooks. Having the same code in a single place really helps with the maintenance work.\n",
"\n",
"The major drawback is that you will need to distribute other files along with your notebook - nothing alarming, but that is a point you have to keep in mind :-)\n",
"\n",
"## What should you place in your external Python files?\n",
"\n",
- "Most probably you want to add functions in it or declarations that are too verbose and tend to hide the logic of your notebook.\n",
- "\n",
- "## What should you **NOT** place in your external Python file?\n",
- "\n",
- "Variables (`initial_position`, etc.), constants (`gravity`, etc.), specific objects that you name (`tennis_ball`), the logic of the notebook code (`setup the physical model, compute object position in time, plot the position on a graph, show the result`) should be visible and readily accessible to the students."
+ "There is no general rule. Utility functions or verbose code used to generate interactive figures tend to hide the logic of your notebook. They are typical examples of code that you can put in an external file.\n",
+ "However, variables (`initial_position`, etc.), constants (`gravity`, etc.), specific objects that you name (`tennis_ball`), the logic of the notebook code (`setup the physical model, compute object position in time, plot the position on a graph, show the result`) should probably be visible and readily accessible to the students."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Using python's ```import``` [recommended method]\n",
"By using the standard ```import``` mechanism from Python, you can also load external Python files\n",
"\n",
- "Here is the content of the library file placed in `libs/mylib.py`:"
+ "Here is the content of the library file placed in `libs/mylib.py` (you can open it by [clicking on this link](libs/mylib.py)):"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from IPython.display import Code\n",
"Code('libs/mylib.py')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"With this Python file available, you can **import selectively** the objets you need (classes, functions, variables, etc.) from it:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from libs.mylib import MyLib\n",
"m = MyLib(\"import\")\n",
"m.greet()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that:\n",
"\n",
"* The path to the external Python file uses Python's nomenclature (using ```.``` as separator), which will work on all operating systems.\n",
"* Only the `MyLib class` has been imported, not the `MyLibVariable`\n",
"\n",
"You can also import **everything** (in this case: `MyLib` class and `MyLibVariable`) from the library file:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from libs.mylib import *"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As expected, the lib `MyLibVariable` variable is now available:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"print(MyLibVariable)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"What if you change the code in the Python file? Running the ```import``` line again will not help: imports are only executed once for your current kernel.\n",
"While this is not an issue for anyone just running the notebook, it might be inconvenient for you during the time you are working on the external file and testing it. To take the new Python code from your library into account, you have to:\n",
"\n",
"1. restart your kernel and execute the import again\n",
"1. force the reloading\n",
"\n",
"How do you force Python to actually import your external files? You can use the ```%reload_ext autoreload``` magic for that!"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%reload_ext autoreload"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%autoreload 2"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Once the two cells above have been executed, all imports in the notebook will systematically import the "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from libs.mylib import MyLib"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"m = MyLib(\"import reloaded\")\n",
"m.greet()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Using the magic \"%run\"\n",
"\n",
"Using the magic ```%run filename``` will execute the provided Python file, just like if the Python code was in the cell. This is useful to load Python resources from an external file."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%run libs/mylib.py"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Every time your run the above cell, the python code from the file is executed. So if you change the Python file, you just have to play the cell again."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"m = MyLib(\"%run\")\n",
"m.greet()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that you have to use **UNIX-style** path to reference your files (```libs/mylib.py```, with ```/```s in the path) - which will not work on non-UNIX devices."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"**End of the notebook**"
]
}
],
"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.6.8"
}
},
"nbformat": 4,
"nbformat_minor": 2
}
diff --git a/TeachingExamples/Demonstrations.ipynb b/TeachingExamples/01_Demonstrations.ipynb
similarity index 100%
rename from TeachingExamples/Demonstrations.ipynb
rename to TeachingExamples/01_Demonstrations.ipynb
diff --git a/TeachingExamples/Textbooks.ipynb b/TeachingExamples/02_Textbooks.ipynb
similarity index 100%
rename from TeachingExamples/Textbooks.ipynb
rename to TeachingExamples/02_Textbooks.ipynb
diff --git a/TeachingExamples/Assignments.ipynb b/TeachingExamples/03_Assignments.ipynb
similarity index 100%
rename from TeachingExamples/Assignments.ipynb
rename to TeachingExamples/03_Assignments.ipynb