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
, Makefile
, environment.yml
, showyourwork.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?¶
By default, showyourwork
expects figure scripts to be Python .py
scripts.
Other languages are also supported, but users must provide explicit instructions
on how to produce figures from the corresponding figure scripts. See the Custom workflows
page for details on how to get showyourwork
to recognize non-Python scripts.
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!
Can I nest figure scripts inside folders?¶
The suggested workflow is to place all your figures directly under the src/figures
directory. However, you may nest them under additional subfolders in that directory.
Note that you must change your figure labels accordingly (i.e., if your figure script is
src/figures/some_folder/script.py
, you should label the corresponding figure in LaTeX
as fig:some_folder/script
.) The other catch is that your script will be run from
the src/figures
directory, so just make sure the file is saved to the current
working directory (not the directory the script is in). This is the default behavior
when doing I/O in Python, so it shouldn’t generally be a problem.
What if I’m on Windows?¶
I don’t know! Does it work? Please give me your feedback here. I’m hoping to add unit tests for Windows and add explicit support for it soon, but any help is appreciated!
How do I debug a run?¶
Sometimes it can be difficult to figure out why a run failed from the terminal
output. Try increasing the verbosity of the output to obtain more informative
error messages by specifying verbose: true
in your showyourwork.yml
file. If you’ve fixed an issue and are still getting the same error, you might try
deleting the .showyourwork
folder at the top level of the repo to get rid
of the build cache. You can also try running make clean
, although that will
delete all your build output.
If your local build is passing but the remote (GitHub Actions) build is failing, this is usually due to one of the following:
Missing files on the remote. This can happen if you forgot to
git add
and push the file to the remote repository. Some files are not tracked by default (like things in thedata
directory, non-Python scripts in thefigures
directory, or anything other thantex
andbib
files in thesrc
directory), so you’ll have togit add -f
(force add) them.Missing environment variables. If you’re using the Zenodo upload/download feature, you’ll need to specify an encrypted repository secret called
ZENODO_TOKEN
containing your API access key. See custom_simulation_dependencies for details.
When a remote build fails, an artifact is uploaded called showyourwork-output
(see the docs
for details on how to download it). This is a tarball containing all files in the
root of your repository and all files directly under the src
directory
at the time the build failed, excluding large (> 5MB) files. Poking around here
can sometimes help identify the cause of the failure. You can also try
increasing the verbosity in the .github/workflows/showyourwork.yml
file
(see verbose.)
If none of this helps, please check out the
issues
page for showyourwork
to see if someone has run into the same problem before.
Feel free to open a new one if you don’t see what you’re looking for.
What if I don’t use AASTeX?¶
If you’re not using the AASTeX or
some of the other built-in templates (see Custom workflows),
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, so please check back soon for more or open
an issue.