Initial version of our tutorial

Please cite as:

Greg Wilson (ed.): "Software Carpentry: Lesson Example."  Version

2016.06, June 2016, https://github.com/carpentries/lesson-example,

10.5281/zenodo.58153.

# Introduction to NOVA and NDIP

Welcome to the NOVA tutorial! This guide will walk you through the process of building interactive tools for neutron analysis using the NOVA platform. You will learn how to create a web application that leverages the NOVA libraries to simplify interaction with the Neutron Data Interpretation Platform (NDIP).

## What is NDIP?

The Neutron Data Interpretation Platform (NDIP) is a workflow management system built on top of the Galaxy platform. It is designed to enable modular scientific workflows for the analysis and interpretation of **neutron data**. NDIP provides a range of services including automated data ingestion, job submission, and computational resource management, and visualization and analysis tools.

## What is NOVA?

NOVA is a platform that aims to simplify the development of applications that interact with NDIP. It consists of three core libraries:

*   **`nova-galaxy`**: This library simplifies interaction with the NDIP platform's APIs. It allows developers to easily connect to NDIP, submit jobs, handle parameters, and monitor job progress.

*   **`nova-trame`**: This library facilitates the creation of interactive user interfaces using Trame. Trame is a powerful Python framework for building web-based UIs and visualizations. `nova-trame` provides a consistent look and feel for NOVA applications by simplifying interactions with Trame components (such as Vuetify).

*   **`nova-mvvm`**: This library simplifies implementation of the Model-View-ViewModel (MVVM) design pattern. By utilizing this library, users can create structured applications that are more testable and easier to maintain.

## What Will You Learn?

In this tutorial, you will learn how to use these three core NOVA libraries to build a web-based user interface that allows you to:

*   Connect to NDIP.

*   Reference job definitions from tool XML files.

*   Set parameters for those tools.

*   Submit jobs to NDIP.

*   Monitor the progress of your submitted jobs.

We'll be using example tools from neutron scattering as a demonstration for this tutorial, however, the lessons learned here can be applied to a wide variety of neutron analysis applications. This hands-on tutorial will guide you through each step of the process, empowering you to build your own interactive tools for neutron data analysis.

## Prerequisites

Before starting this tutorial, you will need to have the following:

*   **Basic Python Knowledge:** A basic understanding of Python programming concepts is required.

*   **Python Installation:** You must have Python 3.8 or higher installed on your system.

*   **NDIP Access:** You should have access to a working NDIP system. (Specific details about NDIP access will need to be provided by the instructor.)

*   **Python's Copier Library** We will be using this library to copy generate a starting application from a template. Can likely be installed using `pip install copier`

 No newline at end of file

---

title: "Lesson Design"

redirect_to:

- https://carpentries.github.io/curriculum-development/

questions:

- "How do we design lessons?"

hidden: True

---

Visit our [new curriculum development guide](https://carpentries.github.io/curriculum-development/).

---

title: "GitHub, Markdown, and Jekyll"

teaching: 10

exercises: 0

questions:

- "How are pages published?"

objectives:

- "Explain how GitHub Pages produce web sites from Git repositories."

- "Explain Jekyll's formatting rules."

keypoints:

- "Lessons are stored in Git repositories on GitHub."

- "Lessons are written in Markdown."

- "Jekyll translates the files in the gh-pages branch into HTML for viewing."

- "The site's configuration is stored in _config.yml."

- "Each page's configuration is stored at the top of that page."

- "Groups of files are stored in collection directories whose names begin with an underscore."

---

This episode describes the tools we use to build and manage lessons.

These simplify many tasks, but make other things more complicated.

## Background Resources

Find out more about [setting up a lesson][lesson-setup] and [contributing changes][contributing], including information on using GitHub.

## Repositories on GitHub

Our lessons are stored in Git repositories (or "repos") on GitHub.

We use the term *fork* to mean

"a copy of a GitHub-hosted repo that is also hosted on GitHub"

and the term *clone* to mean

"a copy of a GitHub-hosted repo that's located on someone else's machine".

In both cases,

the duplicate has a reference that points to the original repo.

In an ideal world,

we would put all of the common files used by our lessons

(such as the CSS style files and the image files with project logos)

in a template repo.

The master copy of each lesson would be a fork of that repo,

and each author's working copy would be a fork of that master:

![Forking Repositories]({{ page.root }}/fig/forking.svg)

However, GitHub only allows a user to have one fork of any particular repo.

This creates a problem for us because an author may be involved in writing several lessons,

each with its own repo.

We therefore use [GitHub Importer][github-importer] to create new lessons.

After the lesson has been created,

we manually add the [template repository]({{ site.template_repo }}) as a remote called `template`

to update the lesson when the template changes.

![Repository Links]({{ page.root }}/fig/repository-links.svg)

## GitHub Pages

If a repository has a branch called `gh-pages` (short for "GitHub Pages"),

GitHub publishes its content to create a website for the repository.

If the repository's URL is `https://github.com/USERNAME/REPOSITORY`,

the website is `https://USERNAME.github.io/REPOSITORY`.

GitHub Pages sites can include static HTML pages,

which are published as-is,

or they can use [Jekyll][jekyll] as described below

to compile HTML and/or Markdown pages with embedded directives

to create the pages for display.

> ## Why Doesn't My Site Appear?

>

> If the root directory of a repository contains a file called `.nojekyll`,

> GitHub will *not* generate a website for that repository's `gh-pages` branch.

{: .callout}

We write lessons in Markdown because it's simple to learn

and isn't tied to any specific language.

(The ReStructured Text format popular in the Python world,

for example,

is a complete unknown to R programmers.)

If authors want to write lessons in something else,

such as [R Markdown][r-markdown],

they must generate HTML or Markdown that [Jekyll][jekyll] can process

and commit that to the repository.

A [later episode]({{ page.root }}/04-formatting/) describes the Markdown we use.

> ## Teaching Tools

>

> We do *not* prescribe what tools instructors should use when actually teaching:

> the [Jupyter Notebook][jupyter],

> [RStudio][rstudio],

> and the good ol' command line are equally welcome up on stage.

> All we specify is the format of the lesson notes.

{: .callout}

## Jekyll

GitHub uses [Jekyll][jekyll] to turn Markdown into HTML.

It looks for text files that begin with a header formatted like this:

~~~

---

variable: value

other_variable: other_value

---

...stuff in the page...

~~~

{: .source}

and inserts the values of those variables into the page when formatting it.

The three dashes that start the header *must* be the first three characters in the file:

even a single space before them will make [Jekyll][jekyll] ignore the file.

The header's content must be formatted as [YAML][yaml],

and may contain Booleans, numbers, character strings, lists, and dictionaries of name/value pairs.

Values from the header are referred to in the page as `page.variable`.

For example,

this page:

~~~

---

name: Science

---

{% raw %}Today we are going to study {{page.name}}.{% endraw %}

~~~

{: .source}

is translated into:

~~~

<html>

  <body>

    <p>Today we are going to study Science.</p>

  </body>

</html>

~~~

{: .html}

> ## Back in the Day...

>

> The previous version of our template did not rely on Jekyll,

> but instead required authors to build HTML on their desktops

> and commit that to the lesson repository's `gh-pages` branch.

> This allowed us to use whatever mix of tools we wanted for creating HTML (e.g., [Pandoc][pandoc]),

> but complicated the common case for the sake of uncommon cases,

> and didn't model the workflow we want learners to use.

{: .callout}

## Configuration

[Jekyll][jekyll] also reads values from a configuration file called `_config.yml`,

which are referred to in pages as `site.variable`.

The [lesson template]({{ site.template_repo }}) does *not* include `_config.yml`,

since each lesson will change some of its value,

which would result in merge collisions each time the lesson was updated from the template.

Instead,

the [template]({{ site.template_repo }}) contains a script called `bin/lesson_initialize.py`

which should be run *once* to create an initial `_config.yml` file

(and a few other files as well).

The author should then edit the values in the top half of the file.

## Collections

If several Markdown files are stored in a directory whose name begins with an underscore,

[Jekyll][jekyll] creates a [collection][jekyll-collection] for them.

We rely on this for both lesson episodes (stored in `_episodes`)

and extra files (stored in `_extras`).

For example,

putting the extra files in `_extras` allows us to populate the "Extras" menu pulldown automatically.

To clarify what will appear where,

we store files that appear directly in the navigation bar

in the root directory of the lesson.

[The next episode]({{ page.root }}/03-organization/) describes these files.

{% include links.md %}