Project Pythia Notebook Template

How to Use This Page¶

This page is designed as a template. As such, each section contains instructions for the content added to the equivalent section of a new notebook, with the exception of this section, and the Setting Up a New Notebook section. Because this is not a tutorial, the overall structure of the page does not need to be cohesive.

Setting Up a New Notebook¶

This section lists the first steps for configuring a Jupyter Notebook for inclusion in Pythia Foundations. First, if you have an image relevant to your notebook, such as a logo, link to this image at the top of the notebook. The following Markdown example illustrates the correct technique for linking such an image:

![<image title>](http://link.com/to/image.png "image alt text")

You can also use an img tag in raw HTML to embed your logo or other image. Second, make sure to add an HTML alt tag to any image in your notebook. This includes any type of image, including logos, wherever and however they appear in your notebook. Adding this tag improves accessibility and allows more people to properly access your notebook.

Project Pythia Logo

Project Pythia Notebook Template¶

Each notebook must be properly titled with a top level Markdown header, i.e., a header title prefixed by a single # mark. Nowhere else in the notebook should you use a top level header. This header will be automatically used by the Pythia book-building process to generate the page title, which will then be added to the navbar, table of contents, etc. As such, the header needs to be short, concise, and descriptive. After the header line, add a separate Jupyter Notebook cell with the text ---. This adds a separating line used to separate the title from the overview and prerequisites. This technique will also be used later to separate other sections.

Overview¶

If your notebook contains an introductory paragraph, include the paragraph at the start of this section. Such paragraphs must be short, and relevant to the content of the notebook. After the introductory paragraph, it is required to list the notebook topics, in the format shown below:

This is a numbered list of the specific topics
These should map approximately to your main sections of content
Or each second-level, ##, header in your notebook
Keep the size and scope of your notebook in check
And be sure to let the reader know up front the important concepts they’ll be leaving with

Prerequisites¶

This part of the Pythia Notebook Template was inspired by another template; in this case, the template for the Jupyter Book known as The Turing Way.

Following the overview section, the prerequisites section must enumerate a list of concepts and Python packages. These concepts and packages must comprise the knowledge that readers of your notebook must know and understand in order to successfully learn the notebook material. Each concept or package listed must link to a Pythia Foundations tutorial, or to a relevant external resource. To build the prerequisite table, first copy the following Markdown table into your notebook. You must then edit the table to contain your notebook prerequisites. Each row must contain the name of the concept, along with a link to the tutorial, either on Pythia Foundations or a relevant external resource. It must also be noted whether the concept is helpful or necessary.

Concepts	Importance	Notes
Intro to Cartopy	Necessary
Understanding of NetCDF	Helpful	Familiarity with metadata structure
Project management	Helpful

Time to learn: You must provide an estimate of the total time to learn the listed concepts. The general rule is to estimate 5 minutes for each subsection in each concept, or 10 minutes for especially lengthy subsections. Add the estimates for each subsection to obtain the time to learn. Also, please note that overestimates are better than underestimates.
System requirements:
- If there are any system, version, or non-Python software requirements for the material in your notebook, these must be listed in a system requirement list.
- If your notebook has no extra requirements, the System Requirements section should be completely removed.
- Note that Python packages do not count as system requirements; these should be listed in the Imports section.

Imports¶

Before beginning this section, add a Markdown cell with a --- divider. This section should list import statements for any Python packages required for your notebook content. Optionally, you can include a description above the code cell as well.

import sys

Your first content section¶

Replace this template section with your first section of tutorial material; all tutorial material should roughly match up with the objectives stated in the Overview section. Your notebook sections should be laid out as a narrative, each containing interspersed Markdown text, images, code cells, and other content as necessary.

# Code cells like this are an essential part of your notebook
print("Hello world!")

A content subsection¶

To provide more detail about concepts in content sections, it is recommended to create content subsections. As shown in this template section, subsections are added through lower-level Markdown headers, and automatically populate navbars, both when viewing the notebook in JupyterLab and when viewing the notebook as a Pythia Foundations tutorial page.

# some subsection code
new = "helpful information"

Another content subsection¶

This subsection was created in the same way as the previous subsection. Subsections often contain detailed information relevant to the material. An example relevant to this template is “Try to avoid using code comments as narrative; instead, let them only exist for brief clarification as needed.”

Your second content section¶

The second content section should roughly match up with the second learning objective of your notebook. For this template, the objective in question is to learn levels of Markdown headers. Below is a demonstration of Markdown header levels; however, be aware that each new header is incorporated into the navbars.

This example is¶

a quick demonstration¶

of further and further¶

header levels¶

Each section in your notebook can also contain $\LaTeX$ equations, enabled through MathJax. In the following example, we illustrate some sample MathJax equations. (Rendering instructions, as well as detailed information about MathJax, can be found in this documentation.)

\begin{align} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{align}

(1)

There are many helpful resources for learning Markdown and customizing Jupyter Markdown cells listed on this useful guide. In addition, there is information on formatting relevant specifically to Jupyter on this Jupyter documentation page. Finally, perfectionism is encouraged in Pythia Foundations, and there are many available resources for formatting notebooks in a perfectionistic manner.

Last Section¶

It is possible to embed raw HTML into Jupyter Markdown cells, as shown above with the Project Pythia logo. This allows for many forms of additional content; the most used form in Pythia is message boxes, as illustrated below. (If you are viewing this page as a Jupyter Notebook, you can also edit the following Markdown cell to view the underlying code.)

Info

This is an info box. Info boxes contain additional information about tutorial concepts.

Making a notebook for Pythia inevitably requires some trial and error for formatting, among other things. If you feel the formatting is lacking in some way, feel free to adjust it in different ways until it is up to your standards. Copying and editing Markdown cells is a good way to try different formatting options.

In addition, there are other types of boxes, known as admonitions, that can be inserted into a tutorial page:

Success

This is a success box. Success boxes are usually placed at the end of a set of examples, and usually show a message relating to the final state of the examples.

Warning

This is a warning box. Warning boxes are usually used to indicate a situation where making a mistake, such as a typo, can cause issues with the tutorial content.

Danger

This is a danger box. Danger boxes are usually used to indicate a situation where making a mistake, such as a typo, can cause more serious issues such as loss of data.

In addition, it is helpful and highly recommended to add cell tags to your Jupyter cells. These tags allow for customization of content display, especially for code cells. In addition, cell tags provide a means for demonstrating errors without breaking any production environments. If you are unfamiliar with cell tags, you can review this brief demonstration provided by Jupyter Book; this demonstration covers cell tags in Jupyter Notebook and Jupyter Lab, as well as fully manual cell tags.

Summary¶

Before adding a summary, you must first add another Markdown cell containing ---, which marks the end of the content body. A good Summary section contains a brief single paragraph that summarizes the tutorial content. The key content elements and their relation to the tutorial objectives should also be covered. Finally, the most important concepts should be listed again in detail.

What’s next?¶

This section should briefly describe the content in the page following your tutorial sequentially. You can find the page sequentially following yours using the Next link at the bottom of the page, or using the sidebar; Jupyter Book should pre-populate this. In addition, if your tutorial leads into other Pythia Foundations content, or tutorials found outside Pythia Foundations, these other tutorials can be linked to as well.

Resources and references¶

In this section, you must provide detailed citations and references to any external content used in your tutorial. Many types of external content are designed in as much detail as Pythia Foundations pages, and crediting the author is essential. In addition, this section can contain links to additional external content, such as reading, documentation, etc. Once this section is complete, your notebook is finished. After giving your new notebook a quick review, you can request the addition of the notebook to Pythia Foundations by sending the team a GitHub Pull Request. Here are a few final notes pertaining to working with Jupyter and Pythia:

In order to confirm that your notebook runs from start to finish without errors, hangs, etc., go to the Kernel menu in Jupyter Lab and select Restart Kernel and Run All Cells.
In order to prepare your notebook to be committed to Pythia Foundations, go to the Kernel menu in Jupyter Lab and select Restart Kernel and Clear All Outputs. After the notebook is committed, the Jupyter cells will be run and optimized for Pythia automatically.
If you wish to take credit for your notebook, you can add contact information in this section; this is completely optional.
It is very important that any code, information, images, etc. referenced in the above sections of your notebook contains appropriate attribution of authorship in this section.
Finally, it is imperative that you must have a legal right to use any content included in your notebook. Do not commit copyright infringement or plagiarism.

The Project Pythia team thanks you greatly for contributing to Pythia Foundations.

Appendix

Pythia Foundations Contributor’s Guide