Initialize Jupyter Book (#3)

* Initialize Jupyter Book

Starting with a minimally modified Jupyter Book initialized with `jupyter-book create book/`. Changed the `_config.yml` to use a proper title and the EGU22 logo. Included a Binder launch button and a footer with CC-BY-4.0 license. Also added a JupyterBook badge to the main README.md.

* Deploy Jupyter Book to GitHub Pages using GitHub Actions

Continuous Integration workflow to build the Jupyter Book's html pages and publish it online to GitHub Pages. Based on https://jupyterbook.org/en/stable/publish/gh-pages.html#automatically-host-your-book-with-github-actions

* Add deploy-book status badge and update Jupyter Book url
* Change citation to Generic Mapping Tools Version 6 for fun
* Change to using author_year citation format
* Add link to EGU22 homepage and divide sidebar into parts

.github/workflows/deploy-book.yml

@@ -0,0 +1,43 @@
+# https://jupyterbook.org/en/stable/publish/gh-pages.html#automatically-host-your-book-with-github-actions
+name: deploy-book
+
+# Only run this when the main branch changes
+on:
+  # Uncomment the 'pull_request' line below to manually re-build Jupyter Book
+  # pull_request:
+  push:
+    branches:
+      - main
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder has been modified.
+    paths:
+      - '.github/workflows/deploy-book.yml'
+      - 'book/**'
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3.0.2
+
+    # Install dependencies
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v3.1.2
+      with:
+        python-version: 3.9
+
+    - name: Install dependencies
+      run: pip install -r book/requirements.txt
+
+    # Build the book
+    - name: Build the book
+      run: jupyter-book build book/
+
+    # Push the book's HTML to github-pages
+    - name: GitHub Pages action
+      uses: peaceiris/actions-gh-pages@v3.8.0
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: book/_build/html

.gitignore

@@ -1,2 +1,5 @@
+# Jupyter Book
+/book/_build/
+
 # Jupyter Notebook
 .ipynb_checkpoints/

README.md

@@ -1,5 +1,8 @@
 # EGU22 SC5.2: Crafting beautiful maps with PyGMT
 
+[![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://www.generic-mapping-tools.org/egu22pygmt)
+[![deploy-book](https://github.com/GenericMappingTools/egu22pygmt/actions/workflows/deploy-book.yml/badge.svg)](https://github.com/GenericMappingTools/egu22pygmt/actions/workflows/deploy-book.yml)
+
 Material for the [PyGMT](https://github.com/GenericMappingTools/pygmt)
 short course at [EGU General Assembly 2022](https://www.egu22.eu)!
 

book/_config.yml

@@ -0,0 +1,47 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Crafting beautiful maps with PyGMT
+author: The PyGMT Team
+logo: logo.svg
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: egu22pygmt.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Launch button settings
+launch_buttons:
+  notebook_interface: jupyterlab
+  binderhub_url: https://mybinder.org
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/GenericMappingTools/egu22pygmt  # Online location of your book
+  path_to_book: book  # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_edit_page_button: true
+  use_issues_button: true
+  use_repository_button: true
+  extra_footer: |
+    <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />
+    This content is licensed under a
+    <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
+
+sphinx:
+  config:
+    bibtex_reference_style: author_year
+    html_show_copyright: false

book/_toc.yml

@@ -0,0 +1,15 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+parts:
+- caption: Details
+  chapters:
+    - title: EGU22 Homepage
+      url: https://www.egu22.eu
+- caption: Tutorials
+  chapters:
+    - file: markdown
+    - file: notebooks
+    - file: markdown-notebooks

book/intro.md

@@ -0,0 +1,11 @@
+# Welcome to your Jupyter Book
+
+This is a small sample book to give you a feel for how book content is
+structured.
+It shows off a few of the major file types, as well as some sample content.
+It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information.
+
+Check out the content pages bundled with this sample book to see more.
+
+```{tableofcontents}
+```

book/markdown-notebooks.md

@@ -0,0 +1,54 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  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
+```

book/markdown.md

@@ -0,0 +1,55 @@
+# 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 Directivs
+
+Roles and directives are two of the most powerful tools in Jupyter Book. They
+are kind of 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).