Introduction#

The showyourwork! workflow is intended to help authors publish open source, replicable, and reproducible scientific articles. It ensures that the article PDF is always in sync with all of the scripts, code, and data used to generate it. It does this automatically—and seamlessly—with the help of the Snakemake workflow management system, the tectonic typesetting engine, and Github Actions CI.

The showyourwork philosophy

Scientific papers should exist as GitHub repositories comprised of LaTeX files, figure scripts, rules to generate and/or access datasets, a platform/environment specification, and nothing else. Anyone should be able to re-generate the article PDF from scratch at the click of a button.

Within the showyourwork! workflow, scientific articles exist as GitHub repositories with a specific layout. Whenever new commits are pushed to the remote repository, a GitHub Action is triggered that automatically builds the article from the input figure scripts, manuscript files, datasets, and conda environment file, following the instructions specified in the Snakefile:

../_images/overview.png

The article PDF (along with a tarball containing all of the output) is then pushed to a special branch (main-pdf by default) on the repository. This article is decorated with badges linking to the exact versions of the files on GitHub used to generate it.

Thanks to the magic of Snakemake, showyourwork! is both lightweight—it should work out-of-the-box for most users—and highly customizable. It also uses intelligent caching to never re-run things it doesn’t have to (like figure scripts that haven’t changed), even when running on the cloud.

Building articles with showyourwork!

Find an open source article you’d like to reproduce or tinker with? Build it in 3 easy steps.

  1. Install the latest version of showyourwork!:

    pip install -U showyourwork
    

  2. Clone the article repository (replace user and repo with the GitHub user name and repository name for the desired project):

    git clone https://github.com/user/repo
    cd repo
    

  3. Build!

    showyourwork
    
    Setting up the workflow...
    Generating the article PDF...
    Done!
    

After installing all the required packages and running any pipeline or figure scripts, this will generate the article PDF ms.pdf in the current working directory.

To get started with showyourwork!, check out the quickstart tutorial. You should also read about the showyourwork GitHub action, LaTeX instructions, and how to build your article locally.

You should also spend some time browsing through the FAQs page. Since showyourwork! is itself a work in progress, new features are still being added frequently. If you spot a bug, have a question, or would like showyourwork! to do something it doesn’t currently support, please feel free to raise a GitHub issue.