> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# psyplot/psyplot-ci-orb

Orb for managing packages within the psyplot visualization framework.
This orb offers installation and automatic building of conda packages, as well as an automated build of Sphinx documentations and an upload to Github Pages


## Commands

### build-docs

Build the docs with sphinx

| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_dir` | string | docs/_build | Directory where to build the docs |
| `builders` | string | html linkcheck | Builders to use |
| `conda_env` | string | docs | Name of the conda environment |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `environment_file` | string | docs/environment.yml | Path to a conda environment file to install additional packages. Must install sphinx, too. If this is empty (or the default file does not exist), we will assume that everything is installed alread in the base conda environment.
 |
| `packages` | string |  | Extra packages to install |
| `source` | string | docs | Directory with the sphinx source files (i.e. with conf.py). |

### build-recipe

Build the conda recipe

| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_args` | string |  | Additional command line arguments for conda-build |
| `build_output` | enum | linux-64 | The output directory for the build |
| `build_tool` | string | mamba | The build tool to use (default mamba) |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `python_version` | string | 3.8 | Python version |
| `recipe_dir` | string | ci/conda-recipe | Path to the recipe to build relative to the project directory |

### codecov

| Parameter | Type | Default | Description |
|---|---|---|---|
| `file` | string | .coverage | Path to the code coverage data file to upload. |
| `flags` | string |  | Flag the upload to group coverage metrics (e.g. unittests | integration | ui,chrome) |
| `token` | env_var_name | CODECOV_TOKEN | Set the private repository token as the value of the variable CODECOV_TOKEN using CircleCI Environment Variables. |
| `upload_name` | string | ${CIRCLE_BUILD_NUM} | Custom defined name of the upload. Visible in Codecov UI |
| `validate` | boolean | true | Validate the uploader before uploading the codecov result. |
| `version` | string | latest | Which version of the Codecov Uploader to use (defaults to 'latest') |
| `when` | string | always | When should this step run? |
| `xtra_args` | string |  | Any extra flags as provided by the bash uploader (e.g. `-v -Z`). |

### conda-list

List a conda environment


| Parameter | Type | Default | Description |
|---|---|---|---|
| `conda_env` | string | test | Name of the conda environment |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |

### configure-conda

Configure miniconda

| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch_label` | boolean | true | Use the branch name as a label for the anaconda channel |
| `channels` | string | conda-forge | Further default channels for conda |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `default_branch` | string | develop | Default branch channel for conda |
| `main_channel` | string | psyplot | Main channel to use with channels and for the branches |
| `orb_version` | string | 1.5.33 | Version for the python deploy package to use. See https://anaconda.org/psyplot/psyplot-ci-orb
 |
| `packages` | string | conda-build=3.25.* anaconda-client conda-verify | Extra packages to install into the base environment |

### configure-git

Sets mandatory git config fields to allow creating and pushing of tags. If not set it will default to details from the VCS system, composed from the $CIRCLE_USERNAME variable. If both parameters are set, they will be used instead.
This command has been taken from the official orb-tools-orb at https://github.com/CircleCI-Public/orb-tools-orb/releases/tag/v10.0.5


| Parameter | Type | Default | Description |
|---|---|---|---|
| `user-name` | string |  | Override git user name.
 |

### configure-recipe

Configure the recipe with extra options

| Parameter | Type | Default | Description |
|---|---|---|---|
| `recipe_append` | string |  | The full content for recipe_append.yml |
| `recipe_dir` | string | ci/conda-recipe | Path to the recipe to build relative to the project directory |

### create-release

Create a new tag in the git repository


| Parameter | Type | Default | Description |
|---|---|---|---|
| `draft` | boolean | true | Whether to create a draft release or not. |
| `token` | string |  | The Github API Token to use. If not set, we use the GITHUB_TOKEN environment variable |

### create-tag

Create a new tag in the git repository


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag-prefix` | string | v | The prefix to use for the tag |

### deploy-docs

Deploy the docs to Github Pages

| Parameter | Type | Default | Description |
|---|---|---|---|
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `deploy_dir` | string | docs/_build/html | The docs to deploy |
| `dry_run` | boolean | false | Do not change anything on Github, just do a dry run |
| `fingerprint` | string |  | The ssh fingerprint used for deploying to github pages |
| `target_branch` | string | gh-pages | The branch in the git repository to deploy to
 |

### deploy-pkg

Deploy the conda to anaconda.
Note that you need a Context with an ANACONDA_API_TOKEN variable set or use the token parameter.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch_label` | boolean | true | Use the branch name as a label for the anaconda channel |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `dry_run` | boolean | false | Do not change anything on anaconda, just do a dry run |
| `label` | string | main | The channel label to deploy to |
| `orb_version` | string | 1.5.33 | Version for the python deploy package to use. See https://anaconda.org/psyplot/psyplot-ci-orb
 |
| `python_version` | string | 3.8 | Python version |
| `recipe_dir` | string | ci/conda-recipe | Path to the recipe to build relative to the project directory |
| `token` | string |  | Anaconda API token. This should be set through a context on CircleCI. If this is not set, we'll assume it's $BINSTAR_API_TOKEN or $ANACONDA_API_TOKEN
 |

### deploy-pypi

Upload the python package to pypi.io

| Parameter | Type | Default | Description |
|---|---|---|---|
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `dry_run` | boolean | false | Do not make an upload, only a dry run |
| `pypi_password` | string |  | User password for pypi upload. We recomment to set this via the TWINE_PASSWORD environment variable in a context.
 |
| `pypi_user` | string |  | User name for pypi upload. We recomment to set this via the TWINE_USERNAME environment variable.
 |

### install

Install and build the conda package


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch_label` | boolean | true | Use the branch name as a label for the anaconda channel |
| `channels` | string | conda-forge | Further default channels for conda |
| `checkout` | boolean | true | Do a checkout |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `default_branch` | string | develop | Default branch channel for conda |
| `install_opengl` | boolean | true | Whether to install opengl (necessary for GUI-based applications) or not
 |
| `main_channel` | string | psyplot | Main channel to use with channels and for the branches |
| `packages` | string | conda-build anaconda-client conda-verify | Extra packages to install into the base environment |

### install-conda

Setup linux environment and install miniconda

| Parameter | Type | Default | Description |
|---|---|---|---|
| `condadir` | string | ~/miniconda3 | Install location for anaconda |

### install-opengl

"Install openGL for GUI-based applications (such as psyplot-gui or psy-view)"


### install-packages

Run tests in parallel using circleci


| Parameter | Type | Default | Description |
|---|---|---|---|
| `conda_env` | string | test | Name of the conda environment |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `packages` | string |  | Extra packages to install |

### run-job

Command to run jobs conditionally

| Parameter | Type | Default | Description |
|---|---|---|---|
| `run-job` | boolean | true | Whether to run the job or stop it. |

### run-parallel-tests

Run tests in parallel using circleci


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_refs` | boolean | false | Build reference figures |
| `conda_env` | string | test | Name of the conda environment |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `pytest_args` | string |  | Any arguments passed to the pytest call |
| `reference_figures` | string | tests/reference_figures | Path to the reference figures |
| `test_dir` | string | tests | Path to the test directory |
| `test_figures` | string | tests/test_figures | Path to the test figures |
| `test_upload_dir` | string | test-results | Path to the directory where to store XML test files |

### setup-conda-env

Setup a conda environment


| Parameter | Type | Default | Description |
|---|---|---|---|
| `conda_env` | string | test | Name of the conda environment |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `environment_file` | string | ci/environment.yml | Path to the conda environment file |
| `packages` | string |  | Extra packages to install |
| `python_version` | string | 3.8 | Python version to use. This does only have an effect if we do not use an environment file. |
| `recipe_dir` | string | ci/conda-recipe | Path to the recipe to build relative to the project directory |

### test-dist

Test the dist for pypi via twine check

| Parameter | Type | Default | Description |
|---|---|---|---|
| `condadir` | string | ~/miniconda3 | Install location for anaconda |

### trigger-release-workflow

Check whether the commit message suggests a new release and if so, cancel the workflow.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout` | boolean | true | Checkout as a first step? Default is true
 |
| `pipeline-param-map` | string | {\"deploy-release\": true} | Map of pipeline parameters that the new pipeline will be invoked with. Make use of this to target the release workflow that should be triggered and exclude other workflows from being triggered.
 |
| `token-variable` | env_var_name | CIRCLE_TOKEN | Name of environment variable containing your personal CircleCI API token
 |

## Jobs

### build-docs

Install and build the conda package


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_dir` | string | docs/_build | Directory where to build the docs |
| `builders` | string | html linkcheck | Builders to use |
| `conda_env` | string | docs | Name of the conda environment |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `environment_file` | string | docs/environment.yml | Path to a conda environment file to install additional packages. Must install sphinx, too. If this is empty (or the default file does not exist), we will assume that everything is installed alread in the base conda environment.
 |
| `exec_environment` | executor | default | Set a custom executor for your job testing environment. By defeault the machine image will be used. Use "macos" for building on OS X. |
| `packages` | string |  | Extra packages to install |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `source` | string | docs | Directory with the sphinx source files (i.e. with conf.py). |
| `workspace` | string | ~ | A workspace to attach. Attach none if empty. |

### create-tag

Create a new tag in the git repository


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout` | boolean | true | Whether to perform the CircleCI checkout step.
 |
| `draft-release` | boolean | true | Whether to create the release as a draft or publish it directly.
 |
| `exec_environment` | executor | default | Set a custom executor for your job testing environment. By defeault the machine image will be used. Use "macos" for building on OS X. |
| `github-token` | string |  | The Github API Token to use. If not set, we use the GITHUB_TOKEN environment variable
 |
| `publish-release` | boolean |  | Publish the created tag as release on github
 |
| `publish-version-tag` | boolean |  | Push a git tag describing the release that was just published? If `true`, make sure to pass SSH fingerprints, as well
 |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `ssh-fingerprints` | string |  | The fingerprint of the SSH key to use for pushing to github |
| `tag-prefix` | string | v | The prefix to use for the tag |
| `user-name` | string |  | Override git user name.
 |
| `workspace` | string | ~ | A workspace to attach. Attach none if empty. |

### deploy-docs

Install and build the conda package


| Parameter | Type | Default | Description |
|---|---|---|---|
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `deploy_dir` | string | docs/_build/html | The docs to deploy |
| `dry_run` | boolean | false | Do not change anything on Github, just do a dry run |
| `exec_environment` | executor | default | Set a custom executor for your job testing environment. By defeault the machine image will be used. Use "macos" for building on OS X. |
| `fingerprint` | string |  | The ssh fingerprint used for deploying to github pages |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `target_branch` | string | gh-pages | The branch in the git repository to deploy to
 |
| `workspace` | string | ~ | A workspace to attach. Attach none if empty. |

### deploy-pkg

Install and build the conda package


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch_label` | boolean | true | Use the branch name as a label for the anaconda channel |
| `build_pkg` | boolean | false | Build the package prior to deployment |
| `build_tool` | string | mamba | The build tool to use (default mamba) |
| `channels` | string | conda-forge | Further default channels for conda |
| `checkout` | boolean | false | Do a checkout |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `dry_run` | boolean | false | Do not change anything on anaconda, just do a dry run |
| `exec_environment` | executor | default | Set a custom executor for your job testing environment. By defeault the machine image will be used. Use "macos" for building on OS X. |
| `install` | boolean | false | Install conda prior to deployment |
| `label` | string | main | The channel label to deploy to |
| `python_version` | string | 3.8 | Python version |
| `recipe_append` | string |  | The full content for recipe_append.yml |
| `recipe_dir` | string | ci/conda-recipe | Path to the recipe to build relative to the project directory |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `token` | string |  | Anaconda API token. This should be set through a context on CircleCI. If this is not set, we'll assume it's $BINSTAR_API_TOKEN or $ANACONDA_API_TOKEN
 |
| `workspace` | string | ~ | A workspace to attach. Attach none if empty. |

### deploy-pypi

Test the dist for pypi via twine check

| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout` | boolean | false | Do a checkout |
| `condadir` | string | ~/miniconda3 | Install location for anaconda |
| `dry_run` | boolean | false | Do not make an upload, only a dry run |
| `pypi_password` | string |  | User password for pypi upload. We recomment to set this via the TWINE_PASSWORD environment variable in a context.
 |
| `pypi_user` | string |  | User name for pypi upload. We recomment to set this via the TWINE_USERNAME environment variable.
 |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `workspace` | string | ~ | A workspace to attach. Attach none if empty. |

### install-and-build

Install and build the conda package


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_args` | string |  | Additional command line arguments for conda-build |
| `build_dir` | string | docs/_build | Directory where to build the docs |
| `build_docs` | boolean | true | Build the documentation |
| `build_output` | enum | linux-64 | The output directory for the build |
| `build_recipe` | boolean | true | Build the conda recipe |
| `build_tool` | string | mamba | The build tool to use (default mamba) |
| `builders` | string | html | Builders to use |
| `channels` | string | conda-forge | Further default channels for conda |
| `checkout` | boolean | true | Do a checkout |
| `conda_env` | string | test | Name of the conda environment for the tests |
| `condadir` | string | ~/miniconda3 | Install location for anaconda. Must end with miniconda3! |
| `default_branch` | string | develop | Default branch channel for conda |
| `docs_conda_env` | string | docs | Name of the conda environment for building the docs |
| `docs_environment` | string | docs/environment.yml | Path to a conda environment file to install additional packages. Must install sphinx, too. If this is empty (or the default file does not exist), we will assume that everything is installed alread in the base conda environment.
 |
| `env_packages` | string |  | Extra packages to install |
| `environment_file` | string | ci/environment.yml | Path to the conda environment file |
| `exec_environment` | executor | default | Set a custom executor for your job testing environment. By defeault the machine image will be used. |
| `install_opengl` | boolean | true | Whether to install opengl (necessary for GUI-based applications) or not
 |
| `main_channel` | string | psyplot | Main channel to use with channels and for the branches |
| `packages` | string | conda-build anaconda-client conda-verify | Extra packages to install into the base environment |
| `python_version` | string | 3.8 | Python version |
| `recipe_append` | string |  | The full content for recipe_append.yml |
| `recipe_dir` | string | ci/conda-recipe | Path to the recipe to build relative to the project directory |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `setup_env` | boolean | true | Setup a conda environment with the build package |
| `source` | string | docs | Directory with the sphinx source files (i.e. with conf.py). |
| `test_dist` | boolean | true | Build and test the python package with setuptools and twine |
| `workspace` | string | ~ | A workspace to attach. Attach none if empty. |

### test-parallel

Install and build the conda package


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_refs` | boolean | false | Build reference figures |
| `codecov` | boolean | true | Upload test results to codecov.io |
| `conda_env` | string | test | Name of the conda environment |
| `condadir` | string | ~/miniconda3 | Install location for anaconda. Must end with miniconda3! |
| `exec_environment` | executor | default | Set a custom executor for your job testing environment. By defeault the machine image will be used. |
| `packages` | string |  | Extra packages to install |
| `parallelism` | integer | 4 | How many parallel jobs to execute |
| `pytest_args` | string |  | Any arguments passed to the pytest call |
| `reference_figures` | string | tests/reference_figures | Path to the reference figures |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `test_dir` | string | tests | Path to the test directory |
| `test_figures` | string | tests/test_figures | Path to the test figures |
| `test_upload_dir` | string | test-results | Path to the directory where to store XML test files |
| `workspace` | string | ~ | A workspace to attach. Attach none if empty. |

### trigger-release-workflow

Trigger a new release workflow.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout` | boolean | true | Checkout as a first step? Default is true
 |
| `pipeline-param-map` | string | {\"deploy-release\": true} | Map of pipeline parameters that the new pipeline will be invoked with. Make use of this to target the release workflow that should be triggered and exclude other workflows from being triggered.
 |
| `run-job` | boolean | true | Whether to run the job or stop it. |
| `token-variable` | env_var_name | CIRCLE_TOKEN | Name of environment variable containing your personal CircleCI API token
 |

## Executors

### default

The default machine executor


### macos

The default macos executor with xcode 12.2.0


## Examples

### example

Sample example description.


```yaml
version: '2.1'
orbs:
  <orb-name>: <namespace>/<orb-name>@1.2.3
workflows:
  use-my-orb:
    jobs:
      - <orb-name>/<job-name>
```