rsp-environments.yaml: metadata about the science platform environments

Source data about the RSP environments that can be used to write environment-specific documentation is maintained in a file called rsp-environments.yaml at the root of this documentation repository. This page describes that file, and how to maintain it.

File layout and schema

The rsp-environments.yaml file consists of a mapping of RSP environments. These keys closely correspond to RSP environments in the Phalanx deployment repository, though they are made to conform to python variable name syntax since they are used as tags for the Sphinx builds (see the tox.ini file). The value for each environment is a mapping that describes metadata about the environment.

type	object
additionalProperties	type	object
	properties
	phalanx	The environment name in phalanx (corresponding to the values files in https://github.com/lsst-sqre/phalanx/tree/master/science-platform).
		type	string
	primary	Set to true only for the primary user-facing RSP. This documentation corresponds to the root URL nb.lsst.io.
		type	boolean
	name	Human-readable name for the RSP environment.
		type	string
	vpn	True if the environment requires any type of VPN for access.
		type	boolean
	ltdedition	The edition name for LSST the Docs.
		type	string
	urls	URLs related to the RSP.
		type	object
		properties
		squareone	The URL of the RSP homepage.
			type	string
			format	uri
		nb	The root URL of the notebook aspect in the RSP.
			type	string
			format	uri
	github_teams	Array of GitHub team names for GitHub-OAuth based Notebook Aspect access. These correspond to the Gafaelfawr values files: https://github.com/lsst-sqre/phalanx/tree/master/services/gafaelfawr
		type	array
		items	type	string
		uniqueItems	True

Linting and data maintenance

The rsplint.py script lints the contents of rsp-environments.yaml using the Phalanx deployment repository as a source of truth. In turn, rsplint.py is run as a Git hook through the pre-commit framework so that rsp-environments.yaml is validated regularly during documentation builds:

• whenever you run pre-commit run --all-files on the command line

• whenever you commit a change to rsp-environments.yaml

• during any build in GitHub Actions

If rsplint.py, through pre-commit, detects a mismatch between values in rsp-environments.yaml and the Phalanx deployment repository, you will need to update rsp-environments.yaml.

Adding or removing an environment

If you are adding a new RSP environment to the documentation build, or removing an existing environment there are a number of files to consider:

• Update rsp-environments.yaml

• Update tox.ini

• Update GitHub Actions, particularly .github/workflows/ci.yaml

• Update any jinja directives in the source content