Add getting started and installation instructions to the welcome page

.github/workflows/deploy-book.yml

@@ -4,7 +4,7 @@ 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:
+  pull_request:
   push:
     branches:
       - main

book/_toc.yml

@@ -4,11 +4,13 @@
 format: jb-book
 root: intro
 parts:
-- caption: Details
+- caption: 🔗 Details
   chapters:
     - title: EGU22 Homepage
       url: https://www.egu22.eu
-- caption: Tutorials
+    - title: Course materials on GitHub
+      url: https://github.com/GenericMappingTools/egu22pygmt
+- caption: 🧑‍🏫 Tutorials
   chapters:
     - file: first-figure
     - file: ecosystem

book/intro.md

@@ -1,11 +1,89 @@
-# Welcome to your Jupyter Book
+# 🥳 Welcome to the EGU22 PyGMT short course
 
-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.
+This Jupyter book contains [PyGMT](https://www.pygmt.org/v0.6.1) tutorials
+for producing maps and doing geospatial data processing 🌍
 
-Check out the content pages bundled with this sample book to see more.
+- [Anatomy of a PyGMT figure](first-figure) by [Leonardo Uieda](https://orcid.org/0000-0001-6123-9515)
+- [Integration with the scientific Python ecosystem 🐍](ecosystem) by [Max Jones](https://orcid.org/0000-0003-0180-8928)
+- [Making some Mars maps with pygmt](Mars_Maps) by [André Luiz Belém](https://orcid.org/0000-0002-8865-6180)
+- [LiDAR Point clouds to 3D surfaces ✨➡️🏔️](lidar_to_surface) by [Wei Ji Leong](https://orcid.org/0000-0003-2354-1988)
 
-```{tableofcontents}
+
+Each tutorial is rendered on this website for easy viewing 👀, but they are all
+Jupyter notebooks designed to be ran interactively 💫. See the instructions
+below on how you can start running the tutorials in no time! 🚀
+
+# 🌠 Quickstart
+
+To run these notebooks in an interactive Jupyter session online,
+🖱️ click on the button below to launch on regular
+[Binder](https://mybinder.readthedocs.io/en/latest/index.html).
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/GenericMappingTools/egu22pygmt/main)
+
+Alternatively, you can go to a specific tutorial page, hover over the rocket 🚀
+icon on the top right, and click 'Binder'.
+
+# 💻 Running the notebooks locally
+
+If you prefer to run the 🧑‍🏫 tutorials with a local installation of PyGMT, then
+follow along! For this EGU22 short course, we recommend creating a virtual
+conda environment and installing the 🐍 Python libraries inside.
+
+:::{tip} For users comfortable with using `git`, feel free to ⬇️ download or
+clone the repository containing the short course materials directly using
+`git clone https://github.com/GenericMappingTools/egu22pygmt.git`
+:::
+
+Here's the instructions to install the `egu22pygmt` environment:
+
+1. Ensure that you have the
+   [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html)
+   package manager installed (e.g. via
+   [`miniconda`](https://docs.conda.io/en/latest/miniconda.html) or
+   [Anaconda](https://www.anaconda.com/products/distribution)).
+   You can also use [`mamba`](https://mamba.readthedocs.io/en/latest/installation.html#fresh-install)
+   which tends to be a ⚡ faster alternative.
+
+2. Make a folder called 'egu22pygmt'. This will be where you will put all the
+   Jupyter notebooks and data files 🗃️ used in the short course.
+
+3. Download a copy of the 'environment.yml' file which contains a 📄 list of
+   dependencies required to run the tutorials in this short course. Get it at
+   https://github.com/GenericMappingTools/egu22pygmt/blob/main/environment.yml.
+
+4. Run the following commands on the 🧑‍💻 command-line to create the virtual
+   environment
+
+    ```bash
+    cd /path/to/egu22pygmt
+    conda create --name egu22pygmt --file environment.yml
+    ```
+
+5. Once the installation is completed 🏁, launch
+   [Jupyter Lab](https://jupyterlab.readthedocs.io) as follows:
+
+    ```bash
+    conda activate egu22pygmt
+    jupyter lab
+    ```
+
+   This should open up a page in your default browser. If not, you can click
+   and open the 🔗 link that says `http://localhost:8888/lab?token=...` in your
+   command-line terminal and this will will take you to the Jupyter Lab page.
+
+6. Download the Jupyter notebook(s) you want to run (e.g.
+   https://www.generic-mapping-tools.org/egu22pygmt/first-figure.html) using
+   either the download button on the ↗️ top right (select '.ipynb') or from
+   GitHub at https://github.com/GenericMappingTools/egu22pygmt/tree/main/book.
+   Make sure to put the *.ipynb file(s) inside of the 'egu22pygmt' folder.
+
+7. Open the Jupyter notebook in the left-pane file browser, e.g. by
+   🖱️ double-clicking on `first-figure.ipynb`. You are now ready to run through
+   the course materials 🎉!
+
+```{note}
+If you're intending to use PyGMT in another project outside of this course,
+please follow the official installation instructions at
+https://www.pygmt.org/latest/install.html
 ```