Command-line reference¶

nbreport¶

nbreport is a command-line client for LSST’s notebook-based report system. Use nbreport to initialize, compute, and upload report instances.

nbreport [OPTIONS] COMMAND [ARGS]...

Options

--log-level <log_level>¶

Logging level (for first-party messages). Default: info.

Options:	warning\|info\|debug

--config-file <config_path>¶: Path to the nbreport user configuration file. Default: ~/.nbreport.yaml.

--server <server>¶: URL of the API host server. Default: https://api.lsst.codes.

--version¶: Show the version and exit.

compute¶

Compute the notebook in a report instance.

Required arguments

INSTANCE_PATH: The path to the report repository directory. You can create an instance with the nbreport init command.

nbreport compute [OPTIONS] INSTANCE_PATH

Options

--timeout <timeout>¶: Timeout for computing individual notebook cells. Default is no timeout.

-k, --kernel <kernel>¶: Name of the Jupyter kernel to use for computing the notebook. The default Python kernel is used if this option is not set.

Arguments

INSTANCE_PATH¶: Required argument

help¶

Show help for any command.

nbreport help [OPTIONS] [TOPIC]

Arguments

TOPIC¶: Optional argument

init¶

Initialize a new report instance.

This command creates a report instance from a report repository. It can work with either local report repositories, or even clone a report repository (from GitHub, for example).

This command contacts the nbreport server to reserve a unique instance ID.

You can also render the report’s template variables by providing -c / --config options. If you don’t render the template variables now, you can do it later with the nbreport render command.

Required arguments

REPO_PATH_OR_URL: The path to the report repository directory on the file system or the URL of a remote Git repository.

nbreport init [OPTIONS] REPO_PATH_OR_URL

Options

-c, --config <template_variables>¶: Template key-value pairs. For example, if the report has a template variable called title, you can provide it as -c title "Hello World!". You can provide multiple -c/–config options. If no variables are set, the notebook’s templated cells are not rendered. You can render the cells laster with the nbreport render command.

-d, --dir <instance_path>¶: Path of the report directory. By default, the report directory is created in the current working directory and is named {{handle}}-{{id}}.

--git-subdir <git_repo_subdir>¶: If cloning from a Git repository and the report is not at the root of that Git repository, set Git repo-relative path to the report with this option.

--git-ref <git_repo_ref>¶: If cloning from a Git repository, check out a specific Git ref (branch or tag name).

--overwrite, --no-overwrite¶: Whether or not to overwrite an instance (on disk). Overwriting is disable by default. If –dir is not set, overwriting should not be necessary.

Arguments

REPO_PATH_OR_URL¶: Required argument

issue¶

Create, compute, and upload a report instance, all-in-one.

Required arguments

REPO_PATH_OR_URL: The path to the report repository directory on the file system or the URL of a remote Git repository.

nbreport issue [OPTIONS] REPO_PATH_OR_URL

Options

-c, --config <template_variables>¶: Template key-value pairs. For example, if the report has a template variable called title, you can provide it as -c title "Hello World!". You can provide multiple -c/–config options.

-d, --dir <instance_path>¶: Path of the report directory. By default, the report directory is created in the current working directory and is named {{handle}}-{{id}}.

--timeout <timeout>¶: Timeout for computing individual notebook cells. Default is no timeout.

-k, --kernel <kernel>¶: Name of the Jupyter kernel to use for computing the notebook. The default Python kernel is used if this option is not set.

--git-subdir <git_repo_subdir>¶: If cloning from a Git repository and the report is not at the root of that Git repository, set Git repo-relative path to the report with this option.

--git-ref <git_repo_ref>¶: If cloning from a Git repository, check out a specific Git ref (branch or tag name).

Arguments

REPO_PATH_OR_URL¶: Required argument

login¶

Obtain a personal access token from GitHub.

Other nbreport subcommands that publish report instances authenticate using your GitHub identity and organization memberships. Run this command first to obtain a personal access token that you can use to authenticate with the other commands.

This command creates a personal access token that is stored in the ~/.nbreport.yaml file.

By using a personal access token, nbreport ensures that your GitHub password never passes through LSST’s servers. You can always revoke a personal access token created by this command by going to https://github.com/settings/tokens.

nbreport login [OPTIONS]

register¶

Register a report with LSST the Docs.

This command only needs to be run once, when you’re creating a new report repository. The command creates a new “product” on LSST the Docs where instances of the report are published.

Required arguments

REPO_PATH: Path to the report repository. The report repository must be a local directory (not a remote Git repository) because the repository’s nbreport.yaml metadata file will be modified. The new metadata created by this command must be committed into the report repository.

nbreport register [OPTIONS] REPO_PATH

Arguments

REPO_PATH¶: Required argument

render¶

Render the notebook template of a newly-create instance.

Use this command to render the notebook template if you didn’t provide template variables with the nbreport init command.

Required arguments

INSTANCE_PATH: The path to the report repository directory. You can create an instance with the nbreport init command.

nbreport render [OPTIONS] INSTANCE_PATH

Options

-c, --config <template_variables>¶: Template key-value pairs. For example, if the report has a template variable called cookiecutter.myvar, you can provide it as -c myvar "Hello World!". You can provide multiple -c/–config options.

Arguments

INSTANCE_PATH¶: Required argument

test¶

Test a notebook repository by instantiating and computing it, but without publishing the result.

Use nbreport test when developing notebook repositories. The nbreport test command does the following steps:

Instantiates a report istance from either a local report directory or a report on GitHub.
Renders the template variables given defaults and user-provided configurations (see the -c option).
Computes the notebook.

Example

nbreport test https://github.com/lsst-sqre/nbreport           --git-subdir tests/TESTR-000 -c title "My first report"

Required arguments

REPO_PATH: The path to the report repository directory.

nbreport test [OPTIONS] REPO_PATH_OR_URL

Options

-c, --config <template_variables>¶: Template key-value pairs. For example, if the report has a template variable called title, you can provide it as -c title "Hello World!". You can provide multiple -c/–config options.

-d, --dir <instance_path>¶: Path of the report directory. By default, the report directory is created in the current working directory and is named {{handle}}-{{id}}.

--id <instance_id>¶: Identifier of the instance. By default, this is test.

--overwrite, --no-overwrite¶: Whether or not to overwrite an existing test instance. Overwriting is enabled by default.

--timeout <timeout>¶: Timeout for computing individual notebook cells. Default is no timeout.

-k, --kernel <kernel>¶: Name of the Jupyter kernel to use for computing the notebook. The default Python kernel is used if this option is not set.

--git-subdir <git_repo_subdir>¶: If cloning from a Git repository and the report is not at the root of that Git repository, set Git repo-relative path to the report with this option.

--git-ref <git_repo_ref>¶: If cloning from a Git repository, check out a specific Git ref (branch or tag name).

Arguments

REPO_PATH_OR_URL¶: Required argument

upload¶

Upload and publish a report instance.

Required arguments

INSTANCE_PATH: The path to the report repository directory. You can create an instance with the nbreport init command. The report repository must already be computed with the nbreport compute command.

nbreport upload [OPTIONS] INSTANCE_PATH

Arguments

INSTANCE_PATH¶: Required argument

Navigation

Command-line reference¶

nbreport¶

compute¶

help¶

init¶

issue¶

login¶

register¶

render¶

test¶

upload¶