Overview

This repository is intended to help authors publish the code that generated the figures and results in a scientific article. It ensures that the compiled article PDF is always in sync with all of the code used to generate it, and that any user that clones the repository can reproduce the PDF from scratch by running

make

It does this automatically—and seamlessly—with the help of the Snakemake workflow management system, the conda package manager, the tectonic typesetting engine, the Zenodo data hosting service, and Github Actions CI.

The showyourwork philosophy

Scientific papers should exist as GitHub repositories comprised of LaTeX files, figure scripts, rules to generate and 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.

Getting started

Click here to get started with a fresh article repository based on showyourwork. Name it whatever you'd like, and make sure to keep the Include all branches field unchecked. Once your repo is created, a GitHub Action will automatically run to finish setting it up. Refresh the page after a few minutes to view the new README.md with instructions on how to get started. Please check out the documentation for more information, examples, tutorials, and FAQs.

Examples and test suite

The showyourwork-template repository contains several branches, each containing a workflow template that demonstrates a particular use case or customization of showyourwork. Upon every release of showyourwork (triggered via a GitHub Actions workflow_dispatch event), these templates are updated and instantiated on the showyourwork-example repository. The following table shows the build status of all of these examples. Please check out the documentation for more information about each one.

branch	build status	output
aa
custom-figure-link
custom-figure-rule
custom-ms-name
expensive-figure
figure-dataset
figure-deps
graphicspath
jinja-yaml
latex-figure
main
mnras
ms-deps
multi-panel-figure
multiple-figures
non-python
non-python-dep
simple-figure
static-figure
zenodo-tarball
zenodo-tarball-manual

Attribution

We're working on writing up a citeable paper on showyourwork, but in the meantime, please consider citing this paper, in which we first introduced showyourwork:

@ARTICLE{Luger2021,
       author = {{Luger}, Rodrigo and {Bedell}, Megan and {Foreman-Mackey}, Daniel and {Crossfield}, Ian J.~M. and {Zhao}, Lily L. and {Hogg}, David W.},
        title = "{Mapping stellar surfaces III: An Efficient, Scalable, and Open-Source Doppler Imaging Model}",
      journal = {arXiv e-prints},
     keywords = {Astrophysics - Solar and Stellar Astrophysics, Astrophysics - Earth and Planetary Astrophysics, Astrophysics - Instrumentation and Methods for Astrophysics},
         year = 2021,
        month = oct,
          eid = {arXiv:2110.06271},
        pages = {arXiv:2110.06271},
archivePrefix = {arXiv},
       eprint = {2110.06271},
 primaryClass = {astro-ph.SR},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2021arXiv211006271L},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

We'd also appreciate it if you'd let us know about your project so we can showcase it as an example on the documentation; consider adding your project to our list of curated repos. And if you're interested in contributing to showyourwork, please consider opening a pull request to tackle one of the many open issues or open a new issue with requests/suggestions for new functionality.