nbreport.yaml file format reference

Every report template repository has an nbreport.yaml file that defines metadata about the report repository. This page describes every field you might find in an nbreport.yaml file, keeping in mind that some fields are optional.

An example nbreport.yaml file:

handle: TESTR-001
title: Characterization Metric Report Demo
git_repo: https://github.com/lsst-sqre/nbreport
ipynb: TESTR-001.ipynb
assets:
  - '**/*.fits'
  - 'mydata.csv'
git_repo_subdir: tests/TESTR-001
ltd_product: testr-001
published_url: https://testr-001.lsst.io
ltd_url: https://keeper.lsst.codes/products/testr-001

handle

The handle is a short identifier for the report series. nbreport does not prescribe a format for handles, but typically there is a series prefix and a serial number suffix:

handle: TESTR-001

title

The title of the report series:

title: Characterization Metric Report Demo

ipynb

Set this field to the name of the report’s Jupyter Notebook file, including the .ipynb extension:

ipynb: TESTR-001.ipynb

assets (optional)

If the report’s Jupyter Notebook relies on other files to execute, and those files are part of the notebook template repository, you can mark them as assets with the assets field. Assets are files, other than the ipynb notebook file, that are copied from the report repository into the report instance when it is rendered and computed (see nbreport init). Unlike the notebook (ipynb file), assets are not templated — they are copied as-is. Directory structure is preserved when asset files are copied from the report repository to the instance.

The assets field takes a list of strings. Each string is a rule for matching asset file paths:

assets:
  - '**/*.fits'
  - 'mydata.csv'

There are three types of rules that designate assets:

  • The file name.

    Simply name the file (relative to the root of the report repository) and it will be designated as an asset:

    assets:
  - 'mydata.csv'
  - 'images/image.fits`

    This example names two files, mydata.csv and images/images.fits, as assets.

  • A directory name.

    The directory, and any files and subdirectories contained inside it, are copied from the report repository to the instance:

    assets:
  - 'images'

    In this example, the entire images directory is designated as an asset.

  • A glob pattern.

    In addition to simple globs (such as *.fits), recursive globs are also supported (**/*.fits):

    assets:
  - 'images/*.fits'
  - '**/*.csv'

    In this example, any FITS file in the images directory is designated as an asset. The second rule designates all CSV files as assets, regardless of what subdirectory contains them.

See also

How to use Python modules in a report notebook template

git_repo (optional)

The URL of the Git repository that this report template is published to. This field is not necessary for local demos, though it is expected by the nbreport register command. Setting this field also helps nbreport include information about the source Git repository in published report instances:

git_repo: https://github.com/lsst-sqre/nbreport

git_repo_subdir (optional)

If the report template is part of a Git repository (git_repo is set), but the repository is not located at the root of that Git repository, you can specify the subdirectory where the report template is located by setting the git_repo_subdir field:

git_repo_subdir: tests/TESTR-001

In this example, the report repository is located in the tests/TESTR-001 directory of the https://github.com/lsst-sqre/nbreport Git repository:

If the report template occupies the root of the Git repository, this field should be omitted:

ltd_product (optional)

This is the name of the report’s registered product name in the LSST the Docs RESTful HTTP API (see also ltd_url):

published_url: https://testr-001.lsst.io

Normally this field is automatically added when you run the nbreport register command to register the report with the nbreport server. If the report is not formally published, this field should not be set.

published_url (optional)

The published_url field is the URL for the homepage of a published report. The homepage indexes all available instances of a report series:

published_url: https://testr-001.lsst.io

Normally this field is automatically added when you run the nbreport register command to register the report with the nbreport server. If the report is not formally published, this field should not be set.

ltd_url (optional)

The ltd_url field is the URL for the report in the LSST the Docs RESTful HTTP API. LSST the Docs is the service that hosts LSST documentation, including notebook-based reports:

ltd_url: https://keeper.lsst.codes/products/testr-001

Normally this field is automatically added when you run the nbreport register command to register the report with the nbreport server. If the report is not formally published, this field should not be set.

See also

The LTD Keeper documentation describes this API.