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

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

Note that if you cloned a third-party repository, and are looking to reproduce their results, you may instead want to run

make fast

which skips the generation step for any file that can instead be downloaded from Zenodo. This can be useful if the paper depends on computationally expensive steps whose output has been stored on Zenodo for quicker re-runs of the workflow.

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

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.

There are several other custom commands accessible via make. Here’s the full list:

make

Default behavior; runs all steps needed to build ms.pdf from scratch.

make arxiv

Builds a tarball of your LaTeX source and figure files for easy upload to the arXiv.

make clean

Deletes all output for the default rule.

make dag

Generates a directed acyclic graph (DAG) of the build process. This is a custom DAG showing the dependencies among showyourwork-managed files. If you’ve defined custom rules in your Snakefile, those won’t show up here; see below under Manual builds for details on how to generate a complete DAG using Snakemake.

make fast

Builds your article PDF, but downloads everything it can from Zenodo, even if there’s a rule to generate something from scratch. Useful to reproduce a third-party result without running expensive simulations.

make lint

Inspects your repository for missing files or improper directory structure and makes suggestions about best practices for reproducible articles.

make report

Generates an HTML build report for the workflow.

make reserve

Reserves a fresh concept DOI on Zenodo or Zenodo sandbox, and prints it to the terminal. Read more about that at id.

make update

Updates showyourwork to the latest release. Remember to check the changelog for information on what’s changed!

make version

Prints the current version of showyourwork.

Using LaTeX Workshop in VSCode

If you edit and build your articles in VSCode, you will have to specify some settings to enable VSCode to find the Makefile in your workspace root directory rather then in the same directory as your manuscript file. Also, to view the PDF in a parallel tab next to your manuscript file, you also have to tell LaTeX Workshop where to find the PDF of the manuscript that showyourwork produces. One solution that has worked for others is to create or edit a workspace-specific settings file in .vscode/settings.json to add some custom settings for LaTeX Workshop:

{
    "latex-workshop.latex.external.build.command": "make",
    "latex-workshop.latex.external.build.args": [],
    "latex-workshop.view.pdf.viewer": "tab",
    "latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%"
}

After this, you can use the LaTeX Workshop: Build LaTeX project command in VSCode to build your manuscript file and have the PDF file auto-update in your VSCode window.

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 them, install snakemake and jinja:

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

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