The showyourwork.yml file¶
This is the configuration file for showyourwork, allowing you to
customize several aspects of the workflow. Below is a list of all
available options.
arxiv_tarball_exclude¶
Type: list
Description: List of of files/paths to exclude from the arXiv tarball.
By default, showyourwork will never include python scripts, matplotlibrc
config files, python and showyourwork temporaries, or .gitignore
files in the tarball. It will also automatically exclude datasets that are
uploaded to/downloaded from Zenodo. This option is useful if there are other
files in your repository – such as static datasets or other kinds of scripts –
that don’t need to be included in the tarball. Note that glob syntax is allowed,
and all paths should be relative to the root of your repository.
Required: no
Default: []
Example:
arxiv_tarball_exclude:
- src/data/dataset.dat
- src/ms.bib
- src/**/*.sh
CI¶
Type: bool
Description: Flag indicating whether or not this is a GitHub Actions continuous integration (CI) build. This is set automatically, but can be overridden here for debugging purposes.
Required: no
Default: (inferred automatically)
Example:
CI: false
dependencies¶
Type: list
Description: List of dependencies for each script. Each entry should be
the path to a script (either a figure script or the TeX manuscript itself)
relative to the repository root. Following each entry, provide a list of
all files on which the script depends. These dependencies may either be
static (such as helper scripts) or programmatically generated (such as
datsets downloaded from Zenodo). In the latter case, instructions on how
to generate them must be provided elsewhere (either via the zenodo key
below or via a custom rule in the Snakefile). In both cases, changes
to the dependency will result in a re-run of the section of the workflow that
executes the script.
Required: no
Default: []
Example:
Tell showyourwork that the figure script my_figure.py depends on
a helper script called helper_script.py:
dependencies:
src/figures/my_figure.py:
- src/figures/utils/helper_script.py
See script dependencies. You can also specify a dependency on a programmatically-generated file:
dependencies:
src/figures/fibonacci.py:
- src/data/fibonacci.dat
See dataset dependencies. Finally, dependencies of the manuscript file are also allowed:
dependencies:
src/ms.tex:
- src/answer.tex
figexts¶
Type: list
Description: List of recognized figure extensions.
Required: no
Default: [pdf, png, eps, jpg, jpeg, gif, svg, tiff]
Example:
figexts:
- pdf
- png
ms¶
Type: str
Description: Path to the main TeX manuscript. Change this if you’d prefer to
name your manuscript something other than src/ms.tex. Note that you should still
keep it in the src/ directory. Note also that the compiled PDF will still be named
ms.pdf regardless of this setting.
Required: no
Default: src/ms.tex
Example:
ms: src/article.tex
scripts¶
Type: list
Description: List of script extensions and instructions on how to execute
them to generate figures. By default, showyourwork expects figure files to
be generated by executing figure scripts with python. You can add custom
rules here to produce figures from scripts with other extensions, or change
the behavior for executing python scripts (such as adding command line
options, for instance). Each entry under scripts should be a file extension,
and under each one should be a string specifying how to generate the figure file
{figure} from the figure script {script}. These two strings are special
placeholders recognized by showyourwork – they resolve to the names of the
two files, relative to the src/figures directory. Note that the command you specify
here will always be executed from within the src/figures directory.
Required: no
Default: []
Example:
We can tell showyourwork how to generate figures from Graphviz .gv
files as follows:
scripts:
gv:
dot -Tpdf {script} > {figure}
tectonic_latest¶
Type: bool
Description: Use the latest version of tectonic (built from source) instead
of the most recent stable version? You shouldn’t normally have to edit this entry.
Required: no
Default: false
Example:
tectonic_latest: true
tectonic_os¶
Type: str
Description: Operating system used for choosing which tectonic
binary to install (only if tectonic_latest is true).
This is usually determined automatically, but can be
overridden. Options are x86_64-unknown-linux-gnu, x86_64-apple-darwin,
or x86_64-pc-windows-msvc.
Required: no
Default: (inferred automatically)
Example:
tectonic_os: x86_64-apple-darwin
verbose¶
Type: bool
Description: Enable verbose output? Useful for debugging runs.
Required: no
Default: false
Example:
verbose: true
zenodo¶
Type: list
Description: A list of datasets to be download from and/or uploaded to
Zenodo. Each entry should be the path to a dataset, followed by keys
specifying information about the Zenodo deposit. These keys depend on the use
case. If the deposit already exists (i.e., it was uploaded manually), then
users need only specify the deposit id. If the
deposit does not exist, and users would like showyourwork to upload it/download
it from Zenodo, they should specify the following keys (most of which are optional):
script,
title,
description,
and creators.
Finally, if the deposit is a tarball consisting of many datasets, users should
also specify the tarball contents.
In all cases, a sandbox and a
token_name key are also accepted.
Note
If an id is not provided, showyourwork will attempt to generate
the dataset by executing the script, but only when running locally.
If successful, it will upload
the file to Zenodo. As long as the script generating the dataset does
not change (and the dataset is not deleted), the script will not be
re-run.
When running on GitHub Actions, however, the script will never be
executed; instead, showyourwork will always download the dataset from
Zenodo. The idea here is to prevent the workflow from executing expensive
operations on the cloud. In order for this to work, however, a deposit must
exist, so you must run your workflow at least once locally before pushing
the changes to GitHub.
Required: no
Default: []
Example: See dataset dependencies, simulation dependencies, dependency tarballs, and dependency tarballs (advanced).
zenodo.<dataset>.contents¶
Type: list
Description: If <dataset> is a .tar.gz file, users should provide
a list of all the files to include in this tarball, which will be automatically
generated by showyourwork. Instructions for generating these individual files
should be provided separately, either via the script
key or via a custom rule in the Snakefile.
Required: yes, but only if <dataset> is a .tar.gz tarball.
Default:
Example: See dependency tarballs.
zenodo.<dataset>.creators¶
Type: list
Description: A list of creators to be listed on the Zenodo record and associated with the record DOI.
Required: no
Default: The GitHub username of the current user
Example: See simulation dependencies.
zenodo.<dataset>.description¶
Type: str
Description: A detailed description of the file, how it was generated, and how it should be used, to be displayed on the Zenodo record page.
Required: no
Default: "File uploaded from <repository-name>"
Example: See simulation dependencies.
zenodo.<dataset>.id¶
Type: int
Description: The ID of a pre-existing Zenodo deposit. This ID is the
number in the URL of a Zenodo record, i.e., 5187276 for
https://zenodo.org/record/5187276. showyourwork will attempt to
download the dataset <dataset> from this record using curl.
Required: yes, but only if the record exists already
Default:
Example: The following snippet
zenodo:
- src/data/fibonacci.dat:
id: 5187276
tells showyourwork to download the file fibonacci.dat from
the Zenodo deposit at https://zenodo.org/record/5187276.
See dataset dependencies.
zenodo.<dataset>.sandbox¶
Type: bool
Description: A flag telling showyourwork whether to use the Zenodo
Sandbox service. This service behaves identically to Zenodo, but files hosted
here are wiped on a random basis, so it is intended only for debugging and
development purposes. This flag should be set to false when development
is complete.
Required: no
Default: false
Example: See simulation dependencies.
zenodo.<dataset>.script¶
Type: str
Description: The path to the python script that generates the <dataset>
(or, if <dataset> is a tarball, the script that generates its contents).
Note that this must be a python script, even if custom script instructions
are provided via the scripts key. To define custom rules for
generating the dataset, see the
dependency tarballs (advanced) example.
Required: yes, unless a custom rule is provided in the Snakefile
Default:
Example: See simulation dependencies.
zenodo.<dataset>.title¶
Type: str
Description: The title of the Zenodo deposit.
Required: no
Default: "<repository-name>:<dataset>"
Example: See simulation dependencies.
zenodo.<dataset>.token_name¶
Type: str
Description: The name of the environment variable containing the
Zenodo access token (or the Zenodo sandbox access token, if
sandbox is true).
To obtain this token, create a Zenodo account
(if you don’t have one already) and
generate a personal access token.
Make sure to give it at least deposit:actions and deposit:write scopes, and store it somewhere
safe. Then, assign your token to an environment variable called ZENODO_TOKEN (or whatever
you set token_name to). I export mine from within my .zshrc or .bashrc config file so that
it’s always available in all terminals.
Finally, to give showyourwork access to Zenodo from GitHub Actions, create a
repository secret
in your GitHub repository with the same name (i.e., ZENODO_TOKEN) and set its value equal to your Zenodo token.
Warning
Never include your personal access tokens in any files committed to GitHub!
Required: no
Default: ZENODO_TOKEN
Example: See simulation dependencies.