From f312b0d2a59848bbbfb4950b22be5fbf349511ce Mon Sep 17 00:00:00 2001 From: Drew Camron Date: Wed, 9 Mar 2022 14:07:23 -0700 Subject: [PATCH 1/2] Drop in Unidata notebook to replace markdown.md --- foundations/markdown.ipynb | 423 +++++++++++++++++++++++++++++++++++++ foundations/markdown.md | 9 - 2 files changed, 423 insertions(+), 9 deletions(-) create mode 100644 foundations/markdown.ipynb delete mode 100644 foundations/markdown.md diff --git a/foundations/markdown.ipynb b/foundations/markdown.ipynb new file mode 100644 index 000000000..734741a39 --- /dev/null +++ b/foundations/markdown.ipynb @@ -0,0 +1,423 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
\n", + "\n", + "
\n", + "\"Unidata\n", + "
\n", + "\n", + "

Jupyter Notebooks Introduction

\n", + "

Unidata Python Workshop

\n", + "\n", + "
\n", + "
\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Jupyter notebooks are a great way to have code, output, images, video, and other information in one place. Notebooks are an ideal tool for the student, research scientist, and even software developer. In this lesson we will go over the basic features of Jupyter notebooks and how to use them." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting Started\n", + "Before you can explore Jupyter notebooks, you need to get them up and running! On the command line, type `jupyter lab` and press `Enter`. This will start up a jupyter lab server and open your default browser connected to this server. On the main page you'll see a file explorer interface. Notice that you cannot go any further up the directory structure that where you started the server. For security reasons, you should run out of a sane sub-directory, not from your home directory. Clicking on a part of the path at the top of the page will change the working directory to that location.\n", + "\n", + "The tabs at the top of the interface `File`, `Running`, and `Clusters` allow you to see the file explorer, state of running notebooks, and parallel execution information. In the `File` tab you can navigate to find notebooks and click to launch them or create new ones. Click on the `New` button to create a new item. New items can be:\n", + "* **Notebook** - Create a new notebook\n", + "* **Text File** - Opens a built-in editor to create text based files\n", + "* **Folder** - Create a new directory\n", + "* **Terminal** - Open an instance of your default terminal" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Notebook Components\n", + "\n", + "Notebooks consist of cells that contain information of various forms. New cells can be created easily by pressing `a` for above for `b` for below the current cell when in command mode.\n", + "\n", + "* Active cells have an outline around them\n", + "* You can navigate with the mouse or arrow keys\n", + "* The cell type is shown in the dropdown menu at the top of the notebook.\n", + "* Think of cells as paragraphs in an essay - they contain a complete set of ideas. Splitting your notebook into properly sized cells is really an art and matter of personal preference." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Using Notebooks\n", + "Notebooks provide an easy-to-use interface to make some potenitally complicated documents. Notebooks operate in one of two modes:\n", + "* **Edit Mode** - Press `Enter` in a cell to enter edit mode.\n", + "* **Command Mode** - Press `ESC` or `Ctrl-m` to enter command mode. The notebook will accept keyboard commands.\n", + "\n", + "### Notebook Menus\n", + "At the top of the notebook window you will find menus containing many useful functions.\n", + "* **File** - Save, copy, export notebooks\n", + "* **Edit** - Move, split, cut, copy, and insert\n", + "* **View** - Modify the notebook's appearance\n", + "* **Run** - Run cells\n", + "* **Kernel** - Interrupt, restart, or change the active kernel\n", + "* **Tabs** - Control jupyter lab tabs\n", + "* **Help** - Access documentation and helpful information\n", + "\n", + "There are lots of keyboard commands so you never have to use a mouse, but for the workshop the `Shift-Enter` shortcut is probably the most useful. It runs the current cell and advances to the next cell. `Ctrl-Enter` will run the current cell without advancing. Shortcuts for split, merge, and delete are also very useful. Don't do these operations by hand - let the computer do the work!\n", + "\n", + "### Notebook Toolbar\n", + "Below the menus at the top of the notebook is a toolbar. It contains buttons to allow you to save, copy, move, etc. as well as run cells and change cell type. Generally you'll be using keyboard shortcuts, but these buttons are available. If you decide to not use the toolbar, it can be hidden in the `View` menu, as can the left file view panel." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Cells\n", + "Notebooks have cells that can be one of three types. Using a mix of cell types can result in a really nice looking and useful document. We'll cover the two you'll be most likely to use: `code` and `markdown` cells.\n", + "\n", + "### Code\n", + "Code cells contain.... well... code. While most commonly associated with Python, Jupyter notebooks can run many kernels including R, Ruby, Julia, and [many more](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). Each notebook can only use a single kernel though. Let's run some simple code in this notebook. Remember, run the cell via the keyboard (`Shift-Enter`) or by pressing the button." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "temperature = 25" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(temperature)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Notice that the standard output is displayed right below the cell that generated it. The system standard error is also displayed below cells." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import sys\n", + "print('I\\'m afraid I\\'ve made a horrible mistake', file=sys.stderr)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The output of the cell appears as it is generated - you can see what's happening as the process is running. The cell below will countdown from 10. If this were a long process that you wanted to interrupt, you could press the button. Try it!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import time \n", + "\n", + "for i in range(10, 0, -1):\n", + " print(i)\n", + " time.sleep(1)\n", + "print(\"Blast off!\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Help on functions can be obtained by putting a `?` afterwards:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "np.arange?" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can also use the tab-completion feature to help save time or find functions." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Markdown Cells\n", + "Markdown is a convenient way to create formatted text using a simple syntax. There are different flavors of markdown, but the [basics](https://daringfireball.net/projects/markdown/basics) are supported across the board and generally cover 80% of the use cases. HTML is also valid in markdown cells. In fact, all of the text and the header of this notebook are markdown/HTML. With markdown you can create headings, embed images, link to other pages, create lists, and more. We aren't going to exhaustively cover markdown, but the essentials can help you make really nice notebooks. Remember, the better your documentation, the more you'll thank yourself later. Think of the notebook as a lab notebook.\n", + "\n", + "#### Basic Text Formatting\n", + "Text can be made **bold** or *italic* by enclosing it in astericks. Notice that a preview even renders in the cell to help you see the formatting that will be applied!\n", + "\n", + "```\n", + "**This text will be bold**\n", + "*This text will be in italics*\n", + "```\n", + "\n", + "---\n", + "\n", + "**This text will be bold**\n", + "\n", + "*This text will be in italics*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Headings\n", + "You can create headings by prepending the text with a number of octothorpes (that's these: #). These go up to five levels deep!\n", + "\n", + "```\n", + "# Heading\n", + "## Sub-Heading\n", + "### Subsub-Heading\n", + "#### Subsubsub-Heading\n", + "##### Subsubsubsub-Heading\n", + "```\n", + "\n", + "---\n", + "\n", + "# Heading\n", + "## Sub-Heading\n", + "### Subsub-Heading\n", + "#### Subsubsub-Heading\n", + "##### Subsubsubsub-Heading\n", + "\n", + "---\n", + "\n", + "**PS** - Notice the horizontal lines helping separate content above? Create them with `---`" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Lists\n", + "You can create ordered and unordered lists with markdown in a format that is much more human readable and editable than making an HTML list. For ordered lists the markdown rendering will even take care of numbering, just use all ones. Remember, let the computer do your work! Sublist formatting is also handled in a sane way automatically.\n", + "\n", + "---\n", + "\n", + "```\n", + "* This is an unordered list\n", + "* It is useful for many things\n", + " * Grocery lists\n", + " * Plans to take over the world\n", + " * Large plans may require multiple lists\n", + "```\n", + "\n", + "---\n", + "\n", + "* This is an unordered list\n", + "* It is useful for many things\n", + " * Grocery lists\n", + " * Plans to take over the world\n", + " * Large plans may require multiple lists\n", + "---\n", + "\n", + "```\n", + "1. Create an ordered list\n", + " 1. Use numbers\n", + " 1. Let the computer handle numbering\n", + " 1. Look super organized\n", + "1. Take over the world\n", + "```\n", + "\n", + "---\n", + "\n", + "1. Create an ordered list\n", + " 1. Use numbers\n", + " 1. Let the computer handle numbering\n", + " 1. Look super organized\n", + "1. Take over the world\n", + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Other Text Formatting\n", + "There are a few other handy text formatting tricks that don't really get their own section, but are nice to see.\n", + "\n", + "Blockquoting is handy for inserting quotes from papers, documents, etc. Just prepend all of the lines with >.\n", + "\n", + "```\n", + "> I was born not knowing and have had only a little time to\n", + "> change that here and there.\n", + "> \\- Richard P. Feynman\n", + "```\n", + "\n", + "---\n", + "\n", + "> I was born not knowing and have had only a little time to\n", + "> change that here and there.\n", + "> \\- Richard P. Feynman\n", + "\n", + "---\n", + "\n", + "The notebook environment also supports so called GitHub flavored markdown. You can tripple quote code blocks and get a nicely formatted output. Providing the langauge even provides syntax highlighting.\n", + "\n", + "---\n", + "\n", + "
\n",
+    "```python\n",
+    "import time \n",
+    "\n",
+    "for i in range(10, 0, -1):\n",
+    "    print(i)\n",
+    "    time.sleep(1)\n",
+    "print(\"Blast off!\")\n",
+    "```\n",
+    "
\n", + "\n", + "---\n", + "\n", + "```python\n", + "import time \n", + "\n", + "for i in range(10, 0, -1):\n", + " print(i)\n", + " time.sleep(1)\n", + "print(\"Blast off!\")\n", + "```\n", + "\n", + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Tables\n", + "\n", + "Making tables is horrible in HTML. Markdown (multi-markdown actually) makes really good looking tables with simple text input.\n", + "\n", + "---\n", + "```\n", + "| Date | Max Temp | Min Temp |\n", + "| ---- | -------- | -------- |\n", + "| 4/12 | 75 | 65 |\n", + "| 4/13 | 80 | 68 |\n", + "| 4/14 | 68 | 50 |\n", + "```\n", + "\n", + "---\n", + "\n", + "| Date | Max Temp | Min Temp |\n", + "| ---- | -------- | -------- |\n", + "| 4/12 | 75 | 65 |\n", + "| 4/13 | 80 | 68 |\n", + "| 4/14 | 68 | 50 |\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Images\n", + "Inserting images in markdown is a one liner!\n", + "```\n", + "![alt text](/path/to/img.jpg \"Title\")\n", + "```\n", + "\n", + "![MetPy Logo](https://github.com/Unidata/MetPy/raw/master/docs/_static/metpy_150x150_white_bg.png \"MetPy's Logo\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Equations\n", + "Notebooks are MathJax-aware, so using a subset of the $\\LaTeX$ syntax, you can easily render complex equations in notebook cells. We don't have time to go into the details of the syntax, but you can find [many tutorials](http://www.math.harvard.edu/texman/) on the topic. Showing a few examples will give you the idea though!\n", + "\n", + "To put equations inline with text enclose them in `$`, to put them on separate lines enclose them in `$$`.\n", + "\n", + "Let's start with a simple example, Newton's second law:\n", + "```\n", + "$$F = m a$$\n", + "```\n", + "\n", + "$$F = m a$$\n", + "\n", + "---\n", + "\n", + "We can also typeset much more complicated equations with a little more syntax effort:\n", + "```\n", + "$$\\left( \\frac{Dv}{Dt} \\right) = -2 \\Omega u \\text{sin}\\phi - \\frac{u^2}{a} \\text{tan}\\phi$$\n", + "```\n", + "\n", + "$$\\left( \\frac{Dv}{Dt} \\right) = -2 \\Omega u \\text{sin}\\phi - \\frac{u^2}{a} \\text{tan}\\phi$$\n", + "\n", + "---\n", + "\n", + "```\n", + "$$\\frac{\\partial\\zeta}{\\partial t} = - V \\cdot \\nabla(\\zeta + f) - \\omega \\frac{\\partial \\zeta}{\\partial p}\n", + "- (\\zeta + f) \\nabla \\cdot V + k \\cdot \\left(\\frac{\\partial V}{\\partial p} \\times \\nabla \\omega \\right)$$\n", + "```\n", + "\n", + "$$\\frac{\\partial\\zeta}{\\partial t} = - V \\cdot \\nabla(\\zeta + f) - \\omega \\frac{\\partial \\zeta}{\\partial p}\n", + "- (\\zeta + f) \\nabla \\cdot V + k \\cdot \\left(\\frac{\\partial V}{\\partial p} \\times \\nabla \\omega \\right)$$" + ] + } + ], + "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.7.3" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/foundations/markdown.md b/foundations/markdown.md deleted file mode 100644 index af786d6ad..000000000 --- a/foundations/markdown.md +++ /dev/null @@ -1,9 +0,0 @@ -# Formatted text in the notebook with Markdown - -```{note} -This content is under construction! -``` - -This section will give a tutorial on formatting text with Markdown: the simple, human-readable text language used extensively in Jupyter notebooks, GitHub discussions, and elsewhere. - -We will show how this useful both in notebooks and other places like GitHub issues. From 13d580fbd15305277fae89d19b920cc22f43f424 Mon Sep 17 00:00:00 2001 From: Drew Camron Date: Wed, 9 Mar 2022 16:34:21 -0700 Subject: [PATCH 2/2] Strip non-markdown and add logo --- foundations/markdown.ipynb | 161 +++---------------------------------- 1 file changed, 13 insertions(+), 148 deletions(-) diff --git a/foundations/markdown.ipynb b/foundations/markdown.ipynb index 734741a39..3990aa2fb 100644 --- a/foundations/markdown.ipynb +++ b/foundations/markdown.ipynb @@ -4,179 +4,44 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "
\n", + "![](https://github.com/dcurtis/markdown-mark/raw/master/png/208x128-solid.png \"markdown-mark logo\")\n", "\n", - "
\n", - "\"Unidata\n", - "
\n", - "\n", - "

Jupyter Notebooks Introduction

\n", - "

Unidata Python Workshop

\n", - "\n", - "
\n", - "
\n", - "\n", - "
" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Jupyter notebooks are a great way to have code, output, images, video, and other information in one place. Notebooks are an ideal tool for the student, research scientist, and even software developer. In this lesson we will go over the basic features of Jupyter notebooks and how to use them." + "# Markdown in Jupyter" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Getting Started\n", - "Before you can explore Jupyter notebooks, you need to get them up and running! On the command line, type `jupyter lab` and press `Enter`. This will start up a jupyter lab server and open your default browser connected to this server. On the main page you'll see a file explorer interface. Notice that you cannot go any further up the directory structure that where you started the server. For security reasons, you should run out of a sane sub-directory, not from your home directory. Clicking on a part of the path at the top of the page will change the working directory to that location.\n", - "\n", - "The tabs at the top of the interface `File`, `Running`, and `Clusters` allow you to see the file explorer, state of running notebooks, and parallel execution information. In the `File` tab you can navigate to find notebooks and click to launch them or create new ones. Click on the `New` button to create a new item. New items can be:\n", - "* **Notebook** - Create a new notebook\n", - "* **Text File** - Opens a built-in editor to create text based files\n", - "* **Folder** - Create a new directory\n", - "* **Terminal** - Open an instance of your default terminal" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Notebook Components\n", - "\n", - "Notebooks consist of cells that contain information of various forms. New cells can be created easily by pressing `a` for above for `b` for below the current cell when in command mode.\n", - "\n", - "* Active cells have an outline around them\n", - "* You can navigate with the mouse or arrow keys\n", - "* The cell type is shown in the dropdown menu at the top of the notebook.\n", - "* Think of cells as paragraphs in an essay - they contain a complete set of ideas. Splitting your notebook into properly sized cells is really an art and matter of personal preference." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Using Notebooks\n", - "Notebooks provide an easy-to-use interface to make some potenitally complicated documents. Notebooks operate in one of two modes:\n", - "* **Edit Mode** - Press `Enter` in a cell to enter edit mode.\n", - "* **Command Mode** - Press `ESC` or `Ctrl-m` to enter command mode. The notebook will accept keyboard commands.\n", - "\n", - "### Notebook Menus\n", - "At the top of the notebook window you will find menus containing many useful functions.\n", - "* **File** - Save, copy, export notebooks\n", - "* **Edit** - Move, split, cut, copy, and insert\n", - "* **View** - Modify the notebook's appearance\n", - "* **Run** - Run cells\n", - "* **Kernel** - Interrupt, restart, or change the active kernel\n", - "* **Tabs** - Control jupyter lab tabs\n", - "* **Help** - Access documentation and helpful information\n", - "\n", - "There are lots of keyboard commands so you never have to use a mouse, but for the workshop the `Shift-Enter` shortcut is probably the most useful. It runs the current cell and advances to the next cell. `Ctrl-Enter` will run the current cell without advancing. Shortcuts for split, merge, and delete are also very useful. Don't do these operations by hand - let the computer do the work!\n", - "\n", - "### Notebook Toolbar\n", - "Below the menus at the top of the notebook is a toolbar. It contains buttons to allow you to save, copy, move, etc. as well as run cells and change cell type. Generally you'll be using keyboard shortcuts, but these buttons are available. If you decide to not use the toolbar, it can be hidden in the `View` menu, as can the left file view panel." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Cells\n", - "Notebooks have cells that can be one of three types. Using a mix of cell types can result in a really nice looking and useful document. We'll cover the two you'll be most likely to use: `code` and `markdown` cells.\n", - "\n", - "### Code\n", - "Code cells contain.... well... code. While most commonly associated with Python, Jupyter notebooks can run many kernels including R, Ruby, Julia, and [many more](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels). Each notebook can only use a single kernel though. Let's run some simple code in this notebook. Remember, run the cell via the keyboard (`Shift-Enter`) or by pressing the button." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "temperature = 25" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "print(temperature)" + "---" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Notice that the standard output is displayed right below the cell that generated it. The system standard error is also displayed below cells." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import sys\n", - "print('I\\'m afraid I\\'ve made a horrible mistake', file=sys.stderr)" + "## Overview" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "The output of the cell appears as it is generated - you can see what's happening as the process is running. The cell below will countdown from 10. If this were a long process that you wanted to interrupt, you could press the button. Try it!" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import time \n", + "## Prerequisites\n", + "| Concepts | Importance | Notes |\n", + "| --- | --- | --- |\n", + "| | | |\n", "\n", - "for i in range(10, 0, -1):\n", - " print(i)\n", - " time.sleep(1)\n", - "print(\"Blast off!\")" + "- **Time to learn**: " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Help on functions can be obtained by putting a `?` afterwards:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import numpy as np\n", - "np.arange?" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You can also use the tab-completion feature to help save time or find functions." + "---" ] }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - }, { "cell_type": "markdown", "metadata": {}, @@ -401,7 +266,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -415,9 +280,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.3" + "version": "3.8.12" } }, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 }