Developer API#
Welcome to the guts of showyourwork!. The backend is fairly complicated given
that showyourwork
is not just a Python package: it is simultaneously 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 import showyourwork
.
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.
Snakefiles#
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
.