Local builds

Using make

This page contains instructions on how to build your article locally; the same applies to reproducing an article created by someone else using showyourwork. As within any GitHub repository, the first thing to do is clone it:

git clone https://github.com/<user>/<repo>

Then, to build the paper, all you have to do is cd into the repository directory and run

make ms.pdf

or, even simpler,

make

This will initialize the showyourwork submodule also install snakemake if haven’t already done these things manually (see below).

You can also use the make command to produce individual figures, for example

make src/figures/my_figure.pdf

or to delete all the output:

make clean

Other commands include generating a directed acyclic graph (DAG) of the build process:

make dag

and generating an HTML build report for the workflow:

make report

Under the hood, the Makefile calls Snakemake, asking for one core by default. You can change this behavior by providing a string of OPTIONS, which get passed to snakemake:

make ms.pdf OPTIONS="-c2"

for instance, to run the workflow on two cores. Type

snakemake --help

for a list of all available options.

Manual builds

While convenient, you don’t need to use the Makefile to run showyourwork. If you want to set up the repo manually, you should clone it as follows

git clone --recurse-submodules https://github.com/<user>/<repo>

or run

git clone https://github.com/<user>/<repo>
git submodule init
git submodule update

to ensure the showyourwork submodule is downloaded and set up properly.

Next, if you don’t already have it, install snakemake:

conda install -y -c defaults -c conda-forge -c bioconda mamba snakemake

This step requires you to have the conda package manager (click here to download it).

Now, to build your paper, run

snakemake -c1 --use-conda ms.pdf

from the top level of your repo. This tells Snakemake to generate the file ms.pdf (your compiled article PDF) on a single machine core (-c1) using the conda package manager. The use-conda flag is imperative! But feel free to request more cores (-c2, -c3, etc.) if needed. You can also check out the myriad options you can pass to Snakemake.

Some other useful commands:

  • To generate a directed acyclic graph (DAG) of the build process, run

    snakemake ms.pdf --dag | dot -Tpdf > dag.pdf
    
  • To generate an HTML build report, run

    snakemake ms.pdf --report
    
  • To delete all output generated when running the ms.pdf rule, run

    snakemake -c1 ms.pdf --delete-all-output