From de3be244b2cbf0f75adfea7656e58080723dd0a6 Mon Sep 17 00:00:00 2001 From: Wei Ji <23487320+weiji14@users.noreply.github.com> Date: Thu, 5 Dec 2024 10:44:53 +1300 Subject: [PATCH] Tidy up tutorial titles and remove placeholder files (#26) * Delete placeholders files from Jupyter Book template * Make all tutorial title headings consistent Ensure all documents have a "Tutorial X - " prefix, use longer title on grid cards, shorter title on sidebar/page heading. --- README.md | 2 +- book/_toc.yml | 3 - book/intro.md | 4 +- book/markdown-notebooks.md | 53 ---------------- book/markdown.md | 55 ---------------- book/notebooks.ipynb | 122 ------------------------------------ book/tut05_topography.ipynb | 2 +- book/tut06_animation.rst | 4 +- 8 files changed, 6 insertions(+), 239 deletions(-) delete mode 100644 book/markdown-notebooks.md delete mode 100644 book/markdown.md delete mode 100644 book/notebooks.ipynb diff --git a/README.md b/README.md index 48a969a..43ae4e6 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Washington, DC 20001, United States | 11:00-11:45 | Tutorial 3 - Integration with scientific Python ecosystem: Xarray (grids) | | 11:45-12:45 | **Lunch** | | 12:45-13:30 | Tutorial 4 - Geophysics (Seismology) | -| 13:30-14:15 | Tutorial 5 - 3-D Topography (Planetary / Antarctic Maps) | +| 13:30-14:15 | Tutorial 5 - 3-D Topography (Planetary / Antarctic maps) | | 14:15-14:45 | **Break** | | 14:45-15:30 | Tutorial 6 - Animations with GMT | | 15:30-17:00 | Final exercises / mini-project | diff --git a/book/_toc.yml b/book/_toc.yml index 7b6afa5..87ac730 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -12,9 +12,6 @@ parts: url: https://github.com/GenericMappingTools/agu24workshop - caption: 🧑‍🏫 Tutorials chapters: - - file: markdown - - file: notebooks - - file: markdown-notebooks - file: tut01_firstfigure - file: tut02_spe_pd_gpd - file: tut03_spe_xarray diff --git a/book/intro.md b/book/intro.md index 9531198..e803b1f 100644 --- a/book/intro.md +++ b/book/intro.md @@ -94,7 +94,7 @@ and [Yvonne Fröhlich](https://orcid.org/0000-0002-8566-0619) ::::{grid} 1 1 1 1 :gutter: 1 -:::{grid-item-card} Tutorial 5 - Topography (Planetary Maps / 3-D Antarctic Maps) +:::{grid-item-card} Tutorial 5 - 3-D Topography (Planetary / Antarctic maps) :img-top: _images/1dfddce0ff606bd7dc3a175aedbd2fc4bde3aeadfadfd339eb30ce1903d049f9.png :link: ./tut05_topography.html by [Wei Ji Leong](https://orcid.org/0000-0003-2354-1988) @@ -108,7 +108,7 @@ and [André Belém](https://orcid.org/0000-0002-8865-6180) {bdg-success-line}`DEM` ::: -:::{grid-item-card} Tutorial 6 - Animations +:::{grid-item-card} Tutorial 6 - Animations with GMT :img-top: _images/5847818951ca8fbc9b86a6f2c67389b6.png :link: ./tut06_animation.html by [Federico Esteban](https://orcid.org/0000-0002-0641-7371) diff --git a/book/markdown-notebooks.md b/book/markdown-notebooks.md deleted file mode 100644 index a057a32..0000000 --- a/book/markdown-notebooks.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -jupytext: - formats: md:myst - text_representation: - extension: .md - format_name: myst - format_version: 0.13 - jupytext_version: 1.11.5 -kernelspec: - display_name: Python 3 - language: python - name: python3 ---- - -# Notebooks with MyST Markdown - -Jupyter Book also lets you write text-based notebooks using MyST Markdown. -See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions. -This page shows off a notebook written in MyST Markdown. - -## An example cell - -With MyST Markdown, you can define code cells with a directive like so: - -```{code-cell} -print(2 + 2) -``` - -When your book is built, the contents of any `{code-cell}` blocks will be -executed with your default Jupyter kernel, and their outputs will be displayed -in-line with the rest of your content. - -```{seealso} -Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html). -``` - -## Create a notebook with MyST Markdown - -MyST Markdown notebooks are defined by two things: - -1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed). - See the YAML at the top of this page for example. -2. The presence of `{code-cell}` directives, which will be executed with your book. - -That's all that is needed to get started! - -## Quickly add YAML metadata for MyST Notebooks - -If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command: - -``` -jupyter-book myst init path/to/markdownfile.md -``` diff --git a/book/markdown.md b/book/markdown.md deleted file mode 100644 index 72018e9..0000000 --- a/book/markdown.md +++ /dev/null @@ -1,55 +0,0 @@ -# Markdown Files - -Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or -in regular markdown files (`.md`), you'll write in the same flavor of markdown -called **MyST Markdown**. -This is a simple file to help you get started and show off some syntax. - -## What is MyST? - -MyST stands for "Markedly Structured Text". It -is a slight variation on a flavor of markdown called "CommonMark" markdown, -with small syntax extensions to allow you to write **roles** and **directives** -in the Sphinx ecosystem. - -For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html). - -## Sample Roles and Directives - -Roles and directives are two of the most powerful tools in Jupyter Book. They -are like functions, but written in a markup language. They both -serve a similar purpose, but **roles are written in one line**, whereas -**directives span many lines**. They both accept different kinds of inputs, -and what they do with those inputs depends on the specific role or directive -that is being called. - -Here is a "note" directive: - -```{note} -Here is a note -``` - -It will be rendered in a special box when you build your book. - -Here is an inline directive to refer to a document: {doc}`markdown-notebooks`. - - -## Citations - -You can also cite references that are stored in a `bibtex` file. For example, -the following syntax: `` {cite}`WesselGenericMappingTools2019` `` will render like -this: {cite}`WesselGenericMappingTools2019`. - -Moreover, you can insert a bibliography into your page with this syntax: -The `{bibliography}` directive must be used for all the `{cite}` roles to -render properly. -For example, if the references for your book are stored in `references.bib`, -then the bibliography is inserted with: - -```{bibliography} -``` - -## Learn more - -This is just a simple starter to get you started. -You can learn a lot more at [jupyterbook.org](https://jupyterbook.org). diff --git a/book/notebooks.ipynb b/book/notebooks.ipynb deleted file mode 100644 index fdb7176..0000000 --- a/book/notebooks.ipynb +++ /dev/null @@ -1,122 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Content with notebooks\n", - "\n", - "You can also create content with Jupyter Notebooks. This means that you can include\n", - "code blocks and their outputs in your book.\n", - "\n", - "## Markdown + notebooks\n", - "\n", - "As it is markdown, you can embed images, HTML, etc into your posts!\n", - "\n", - "![](https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg)\n", - "\n", - "You can also $add_{math}$ and\n", - "\n", - "$$\n", - "math^{blocks}\n", - "$$\n", - "\n", - "or\n", - "\n", - "$$\n", - "\\begin{aligned}\n", - "\\mbox{mean} la_{tex} \\\\ \\\\\n", - "math blocks\n", - "\\end{aligned}\n", - "$$\n", - "\n", - "But make sure you \\$Escape \\$your \\$dollar signs \\$you want to keep!\n", - "\n", - "## MyST markdown\n", - "\n", - "MyST markdown works in Jupyter Notebooks as well. For more information about MyST markdown, check\n", - "out [the MyST guide in Jupyter Book](https://jupyterbook.org/content/myst.html),\n", - "or see [the MyST markdown documentation](https://myst-parser.readthedocs.io/en/latest/).\n", - "\n", - "## Code blocks and outputs\n", - "\n", - "Jupyter Book will also embed your code blocks and output in your book.\n", - "For example, here's some sample Matplotlib code:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from matplotlib import rcParams, cycler\n", - "import matplotlib.pyplot as plt\n", - "import numpy as np\n", - "plt.ion()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Fixing random state for reproducibility\n", - "np.random.seed(19680801)\n", - "\n", - "N = 10\n", - "data = [np.logspace(0, 1, 100) + np.random.randn(100) + ii for ii in range(N)]\n", - "data = np.array(data).T\n", - "cmap = plt.cm.coolwarm\n", - "rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))\n", - "\n", - "\n", - "from matplotlib.lines import Line2D\n", - "custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),\n", - " Line2D([0], [0], color=cmap(.5), lw=4),\n", - " Line2D([0], [0], color=cmap(1.), lw=4)]\n", - "\n", - "fig, ax = plt.subplots(figsize=(10, 5))\n", - "lines = ax.plot(data)\n", - "ax.legend(custom_lines, ['Cold', 'Medium', 'Hot']);" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "There is a lot more that you can do with outputs (such as including interactive outputs)\n", - "with your book. For more information about this, see [the Jupyter Book documentation](https://jupyterbook.org)" - ] - } - ], - "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.8.0" - }, - "widgets": { - "application/vnd.jupyter.widget-state+json": { - "state": {}, - "version_major": 2, - "version_minor": 0 - } - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/book/tut05_topography.ipynb b/book/tut05_topography.ipynb index 88464f3..3bedb0c 100644 --- a/book/tut05_topography.ipynb +++ b/book/tut05_topography.ipynb @@ -5,7 +5,7 @@ "id": "04aad1c8", "metadata": {}, "source": [ - "# 3-D Topography 🏔️\n", + "# **Tutorial 5** - 3-D Topography 🏔️\n", "\n", "In this tutorial, let's use PyGMT to create 3-D perspective plots of Digital Elevation\n", "Models (DEM) over Mars (the planet) and Antarctica (the continent)!\n", diff --git a/book/tut06_animation.rst b/book/tut06_animation.rst index a100579..eec40e6 100644 --- a/book/tut06_animation.rst +++ b/book/tut06_animation.rst @@ -1,5 +1,5 @@ -Making animations ------------------ +**Tutorial 6** - Animations +--------------------------- By F. Esteban (@esteban82)