Developer API#

Welcome to the guts of showyourwork!. The backend is fairly complicated given that showyourwork is not just a Python package: it is simultanteously a wrapper around Snakemake and a child process of Snakemake, as well as a command-line tool, a cookiecutter template, a GitHub Action, and a conda environment manager. The code is wrapped up into a pip-installable Python package, but users should never have to actually import showyourwork into their scripts. Users should only ever interact with the code via the command line interface, which spawns child processes that themselves install showyourwork (since workflows define specific versions of showyourwork to use).

But if you’re reading this, you’re probably interested in learning how showyourwork actually works, and possibly in tweaking it or adding new features. The documentation pages below are divided into four sections. The first section contains documentation for the Python package proper (The showyourwork module), followed by documentation for the scripts that do the heavy lifting during the article build step (Snakemake workflow scripts), the Snakemake rules that run those scripts (Snakemake rules), and the top-level Snakefiles that define the workflow (Snakefiles).

The showyourwork module#

This module contains the user-facing command line interface (cli), definitions for the custom exceptions raised by the workflow (exceptions), as well as the Python backend that interfaces with Snakemake.

Snakemake workflow scripts#

These files are located in showyourwork/workflow/scripts and are executed from the Snakemake rules defined in showyourwork/workflow/rules. They do the heavy lifting for the pipeline, including generating the article graph in the preprocessing step, downloading and extracting Zenodo datasets, and building the article PDF.

Snakemake rules#

These files are located in showyourwork/workflow/rules and contain the main Snakemake rules for the pipeline. These rules either execute simple shell commands (like running Python scripts to generate figures) or call the scripts in showyourwork/workflow/scripts to perform more complex pipeline tasks.


These are the two Snakefiles that control the pipeline. These Snakefiles import all of the Snakemake rules defined in showyourwork/workflow/rules, parse the user config, ingest the user’s custom Snakefile, etc.

Integration tests#

Integration tests are located in tests/integration at the root of the repo. See below for information on how we test all the different moving parts in showyourwork.