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, runsnakemake -c1 ms.pdf --delete-all-output