Local builds¶
Setup¶
While showyourwork
is mainly designed to build your article PDF on the cloud
via GitHub Actions, you’ll likely want to build it locally as well. To get started
with that, clone your repository:
git clone --recurse-submodules https://github.com/<user>/<repo>
or
git clone https://github.com/<user>/<repo>
git submodule init
git submodule update
This makes sure 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).
Build¶
Now, to build your paper, navigate to the top level of your repository and run
snakemake -c1 --use-conda ms.pdf
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
.
Quick-and-dirty¶
As of version 1.0.8
, the showyourwork-template
repository comes with a Makefile
that automates a lot of this stuff. After you clone your repo, you should be able to
just run
make ms.pdf
or, even simpler,
make
to build your article. This will also install snakemake
if you don’t already
have it. You can also use this command to produce individual figures, for example
make src/figures/my_figure.pdf
Under the hood, this is calling Snakemake
with one core (-c1
) and forcing
conda usage (use-conda
). You can edit the Makefile
variables to change these
options or add others.
Other¶
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