Developer API


The API documentation is still under development. Please check back soon for more details.


These modules are located in showyourwork/worfklow/rules and their contents are importted into the global namespace when executing the workflow. The functions and variables defined in these modules are used in several of the rules.

Process the user config settings.

Figure “error” (status) codes.

rules.errors.ScriptDoesNotExist = <rules.errors._ScriptDoesNotExist object>

The figure script does not exist.

rules.errors.ScriptHasUncommittedChanges = <rules.errors._ScriptHasUncommittedChanges object>

The figure script has uncommitted changes.

rules.errors.ScriptNotVersionControlled = <rules.errors._ScriptNotVersionControlled object>

The figure script is not version controlled.

rules.errors.ScriptUpToDate = <rules.errors._ScriptUpToDate object>

The figure script is version controlled and up to date.

Miscellaneous files used throughout the workflow.

class rules.files.files

Houses lists of support files used throughout the workflow.

aux = []

Auxiliary files we copy over to the user’s src/ directory.

cls = {}

Class-specific auxiliary files.

dot_zenodo = []

The .zenodo files in which we store the URL for the datasets We make the PDF generation depend on these so we always have access to the URLs for the icon generation. These are updated in zenodo.smk.

special_figures = ['orcid-id.png', 'showyourwork.pdf']

Figures that are allowed directly in the src/ directory

tectonic = []

Tectonic command

tmp_syw = '.showyourwork-ms'

Temporary tex file.

tmp_xml = '.showyourwork-xml-ms'

Temporary tex file.

unknown = 'unknown-script'

Dummy file dependency for figures w/ unknown parent scripts.

zenodo_files_auto = []

The showyourwork-managed datasets for this article

zenodo_files_manual = []

The manually-uploaded datasets for this article that must be downloaded

Functions used as inputs / params in various rules.


Check that all figures are declared correctly in tex/ms.tex so we can parse them corresponding XML tree.


Return a list of class files needed to compile the PDF.


Return the figure script that produces wildcards.figure.


Return user-specified dependencies of the current figure script.


Return all the figure files required by the manuscript.


Return the path to the LaTeX document class file.

rules.functions.script_name(wildcards, input)

Returns the name of the figure script for the figure rule.

Assumes the first python file in the input is the one that generates the script.

Sets global constants for the workflow.

class rules.paths.abspaths

Absolute paths used throughout the workflow.

user = PosixPath('/path/to/repo')

Path to the user’s repository root

workflow = PosixPath('/path/to/showyourwork')

Path to the showyourwork workflow


Convert a path object to a string containing the posix path.

class rules.paths.relpaths

Relative paths used throughout the workflow.

dot_github = PosixPath('.github')

Path to the showyourwork workflow

figures = PosixPath('src/figures')

Path to the showyourwork workflow

temp = PosixPath('.showyourwork')

Path to the showyourwork workflow

tex = PosixPath('src')

Path to the showyourwork workflow

Collect information about all the datasets we’ll need to upload to/download from Zenodo.

class rules.zenodo.zenodo

Class containing metadata for all Zenodo deposits.

deposit_creators = {}

Zenodo authors for each dataset

deposit_description = {}

Zenodo deposit description for each dataset

deposit_title = {}

Zenodo deposit title for each dataset

file_name = {}

File name for each dataset

file_path = {}

Path to each dataset

generate_deps = {}

List of dependencies of each dataset

generate_shell = {}

Shell command for generating each dataset

sandbox = {}

Use Zenodo sandbox for a particular dataset?

token_name = {}

Zenodo token name (name of an env. var.) for each dataset

zenodo_id = {}

Id for each Zenodo download

zenodo_url = {}

Url for each Zenodo download


These rules are located in files of the same name in the showyourwork/workflow/rules directory with the extension .smk.

rule repo

Generate repository metadata (git url, branch name, commit sha).

rule aux_file

Copy auxiliary tex files to the src directory.

rule tectonic

Install the latest version of tectonic.

rule class_name

Infer the name of the LaTeX document class for the article.

rule class_file

Copy the LaTeX class file to the src directory.

rule tmptexfile

Copy the manuscript to a temporary TeX file for the XML build step.

rule xml

Generate the article XML tree.

rule script_info

Build the figure dependency tree.

rule metadata

Generate article metadata.

rule figure

Generate a figure given a figure script and optional dependencies.

rule texfile

Copy the manuscript to a temporary TeX file for the final build.

rule stylesheet

Generating the showyourwork.sty LaTeX style sheet.

rule pdf

Build the article PDF.

rule arxiv

Build a tarball of the article PDF and all output for posting to the arXiv.

rule download_manual

Download a figure dependency that was manually uploaded to Zenodo.

rule docstrings

Generate simple documentation for the rules in this workflow.


These scripts are located in showyourwork/workflow/scripts and are called from some of the rules defined above.

Upload or downlod a dataset to/from Zenodo. This script is called from the zenodo rule.

Create the output tarball for easy arXiv upload. This script is called from the arxiv rule.

Build the article PDF. This script is called from the pdf rule.

Create the showyourwork stylesheet. This script is called from the stylesheet rule.

Download and install tectonic from source. This script is called from the tectonic rule.

Generate a figure output. This script is called from the figure rule.

Build the article to get the XML tree. This script is called from the xml rule.