Rhode Island Data Discovery Center’s Jupyter Book¶

This repository houses the RIDDC’s Jupyter Book with articles showcasing projects, analyzes and visualizations created using data from the OSM region.

Guidelines for RIDDC Articles.¶

Article Format¶

Articles can be written in Markdown or Jupyter Notebook format (ipynb). In both cases, the first block (cell in ipynb) should start with a title in Markdown followed by the authors’ names.

If the article is divided in sections, use h2 (##) headers for section titles. This will help Jupyter Book to create a table of contents on the right sidebar. Do not use # before a regular paragraph.

For images, use Markdown syntax with caption, in addition add the caption as a blockquote.

If your notebook was created in Colab, make sure you remove the first cell with the Open in Colab badge.

Example:

# Title
> by Jane Doe
> jane@brown.edu 

## Section Header

Paragrah text...

![image](path/to/image.png "Caption for image")
> Caption for image (repeat)

Jupyter Book Docs¶

Please, review the Jupyter Book Documentation before writing new content. They provide a lot of information on how to organize and write content for Jupyter Books.

How to add new notebooks¶

To add new notebooks to RIDDC follow these steps:

• Fork this repository

• Add new notebooks or Markdown formatted articles to the directory riddc/notebooks

• Add an entry to the file riddc/_toc.yml pointing to the notebook(s) you added. Feel free to create a section (refer to the jupyter book documentation)

• Build the Jupyter Book locally (see bellow).

• Commit and push your changes.

• When you’re happy with the changes, open a pull request to this repository. Once approved, an admin member will merge into main and the changes will be auto-deployed.

Usage¶

Install system dependencies¶

• On Mac: download Homebrew and install with brew bundle

  • with the Mac M1 chip, run export HDF5_DIR=/opt/homebrew/opt/hdf5

• On Windows:

  • first download HDF5 from source: https://support.hdfgroup.org/ftp/HDF5/current/bin/

  • download Chocolatey and install with choco install packages.config

If you’d like to develop on and build the riddc book, you should:

• Clone this repository

• cd to the repository

• Download uv

• Run uv sync to install dependencies

Build the book¶

• (Recommended) Remove the existing riddc/_build/ directory with rm -rf riddc/_build/

• Run uv run jupyter-book start

• Note: On Mac, you may need to make the following soft link for the book to build: ln -s /opt/homebrew/share/jupyter/nbconvert ~/Library/Jupyter

A fully-rendered HTML version of the book will be built in ./_build/html/.

Contributors¶

We welcome and recognize all contributions. You can see a list of current contributors in the contributors tab.

Credits¶

This project is created using the excellent open source Jupyter Book project and the executablebooks/cookiecutter-jupyter-book template.