Contributor Guide

Contributor Guide#

To make a great contribution you need to:

  1. Write your book

  2. Build your book

  3. Prepare your book to be added to the library

  4. Submit a request to have your book added

Note

Consider sections 1 and 2 as a style guide. In order to be added to the library, you must have: #. a fully published and hosted book and #. metadata that follows the structure described in section 3!

Write your book#

Each library contribution needs well organized content and a landing page (a readme or intro).

Content:#

Structure your content into one or more sections, each addressing specific themes or topics. Each section contains one or more notebooks (chapters) that delve into the details of the respective theme. How you organize your book is up to you. We have found Lifehacks and Science Bits to be useful sections, as our chapters have generally fallen under one of those two categories, but that is not the only way, and the best way is whatever way is most intuitive given your content.

Lifehacks

Careful breakdowns of technically tricky, unintuitive or cumbersome tasks, e.g., data visualization tips or explanations about how to interact with a data product

Science Bits

Step by step discussion of analysis or exploratory workflow, for example

Paper

Notebooks describing the research behind a published work

Note

Every notebook must have a level 1 header. If it has more than one, the first one will be taken as the title of the chapter within your JupyterBook (you can customize this as far as the library is concerned, but you may find this to be a useful tip as far as your book goes.)

Landing Page:#

There isn't a required structure for your landing page, but we have found that the following elements are appropriate (bolded items are common section titles):

  • Title: Clearly state the title of your Jupyter book.

  • Quick Summary (Byline): Provide a concise summary of your book. This also a good place to include a formatted citation for your book if it has a DOI.

  • Motivation: Offer an overview of the motivation behind building the book. This section should briefly touch on the science or technical skills explored in your chapters. It might also include information about any datasets involved or projects your book is associated with.

  • Author: Provide information about the primary author or authors of the book.

  • Contributors: Check out contrib.rocks for an html snippet with avatars for each contributor to your jupyterbook repo.

  • Structure: Give a quick explanation of the content in each section of the book (more on this below).

  • References: Include notes about any publications associated with the book.

Build your book#

There are various ways to go about this. The most straight forward is to follow the Create your first book tutorial on the JupyterBook website.

A couple of notes:

  • The tutorial project structure is very simple. For an example of a slightly more complex table of contents (_toc.yml), look here.

  • Make sure to modify the _config.yml. Here is an example to help.

    • make sure that path_to_book points to the directory in your repo where your book lives (in the example, this is proxycomposite)

    • gh-import will prompt you for your github username and password, and you will need to follow these instructions about personal access tokens to get a more secure password (github will not accept standard passwords for this purpose)

    • if you don't want the books to execute on build, include:

    execute:
    execute_notebooks: 'off'

  • Include a copy of your book's thumbnail in the directory where your book is and call it logo.png. This is specified in the _config.yml and naming/locating it in a predictable place will save a headache.

Prepare for joining the library#

In order for your book to be added to the library, you will need to provide some additional information we will use to populate various fields.

  1. In the same directory as the _config.yml file, make a folder called meta_data and a folder called thumbnails

  2. In meta_data, make a file called chapter_meta.yml and copy and paste the contents of the C-iTrace PaleoBook chapter_meta.yml to use as template. (The formatting of these files cam be particular, so it highly encouraged to start from one that is functional.)

Here is the top segment:

shortname: C-iTRACE
type: Paleobook
thumbnail: thumbnail.png
parts:
  - caption: Lifehacks
    chapters:
      - shortname: pyODV
        filename: pyODV
        thumbnail: pyodv_demo.png
        tags:
          domains:
            - oceanography
            - tracers
            - data viz
          packages:
            - xarray
            - matplotlib
            - cartopy
            - pandas
            - seaborn
      - shortname: data_on_a_model_grid

This table provides an explanation of each element:

yml excerpt

explanation

shortname

short word or phrase for your book

type

if your book is not a PaleoBook, note the collection it belongs to

thumbnail

the name of the thumbnail image for the whole book (assumed to be .png, if not indicated)

parts

below this will be the sections your book is organized into

caption

the name of the part (e.g. Lifehacks)

chapters

below this will be the notebooks (chapters) included in this section

shortname

the name of the chapter as you want it to appear on the chapter card

filename

the name of the notebook (without .ipynb)

thumbnail

the name of the thumbnail image for this specific chapter (assumed to be .png, if not indicated)

tags

below this are the tags (among three categories: domains, packages, format) assigned to the chapter card in the library (note: tags should be short but may include spaces)

domains

below this are tags related to domain knowledge (e.g. isotopes, linear regression)

packages

below this are tags for packages leveraged in the chapter (e.g. pyleoclim)

Now onto the next chapter! (The next shortname will refer to the next chapter.)

  1. In the thumbnails folder, add one thumbnail for the book, and one thumbnail for each chapter (labeled according to the name indicated in chapter_meta.yml)

Push these additional contributions to your github repo.

Submit a library request#

Once you have a fully built and published JupyterBook with extra metadata, submit a request to be added on github!

  1. Name of the repository: e.g., DISK-proxyComposite

  2. Repo url: e.g., https://github.com/khider/DISK-proxyComposite

  3. Host for the JupyterBook: e.g., https://khider.github.io NOT https://khider.github.io/DISK-proxyComposite/intro.html

  4. User: e.g., khider

  5. Landing suffix (name of the page you want users to land on): e.g., intro.html

Contents