FAQs¶
Below is a non-exhaustive list of frequently asked questions. If you don’t see what you’re looking for here, check out the issues page or feel free to suggest your own FAQ.
What if I already have a repository?¶
We recommend starting your showyourwork
project from scratch by
instantiating the repository template.
If you already have a project in progress (or even completed), you’ll have to do
a bit of re-structuring to get it to conform to the showyourwork
layout. This means
placing everything inside a top-level src
folder, and within that, figure scripts
within the figures
folder, static files within the static
folder, and the TeX file
directly under src
. Next, you’ll have to add the showyourwork
submodule by running
git submodule add https://github.com/rodluger/showyourwork
Finally, copy the files Snakefile
, environment.yml
, and .github/workflow/showyourwork.yml
from the showyourwork template,
and edit them as needed. See the layout guide for details.
What if I’m using Overleaf?¶
We currently don’t support Overleaf projects. We’re thinking about how to do this properly, so
please check back soon for more information. In the meantime, you can develop both your showyourwork
repository and your Overleaf project simultaneously, copying the tex file over to GitHub and the figure
output over to Overleaf manually as needed.
What if I don’t use Python?¶
Currently, showyourwork
requires figure scripts to be Python .py
scripts.
Support for other languages – such as julia
, Jupyter
notebooks, or even
just plain bash
is coming soon! In the meantime, check out Custom workflows for
information on how to override this behavior manually to specify your own figure
generation rules.
What if I don’t use includegraphics
calls?¶
showyourwork
inspects calls to includegraphics
and label
within figure
environments to infer figure dependencies in the workflow. However,
many people use commands like plotone
and plottwo
or user-defined shorthand for
including figures in LaTeX. This should still work! As long as these shortcuts
call includegraphics
somewhere along the line (which they do), showyourwork
should work just fine. Just remember to always label your figures!
How do I debug a run?¶
Sometimes it can be difficult to figure out why a run failed from the terminal output, especially if it’s an error during the LaTeX build. Try increasing the verbosity of the output to obtain more informative error messages:
snakemake -c1 --use-conda ms.pdf --config verbose=true
What if I don’t use AASTeX?¶
If you’re not using the AASTeX LaTeX
template for AAS journals, things should still work as long as you include the
relevant class and style files in the src/
directory alongside your texfile.
You won’t get the snazzy showyourwork
logo at the top of the page, but
everything else should still work. We’re planning on adding explicit support for
other templates (like MNRAS and A&A), so please check back soon for more.
Why do I keep getting a Bad Gateway error?¶
On GitHub Actions you may occasionally run into a 502: Bad Gateway
HTTP
error. These are sporadic and temporary, and are usually due to issues
with downloading the (very large) TeX distributions from archive.org
.
To commiserate with others experiencing this issue, see here.
Other than that, the best thing to do is simply wait a bit and re-run the failed job!