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 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.