FAQs
Contents
FAQs#
Below is a non-exhaustive list of frequently asked questions with suggested answers and solutions. If you don’t find what you’re looking for here, consider taking a look at the issues page on showyourwork! GitHub repo. Also make sure to check out the list of closed issues, where you might find that others have run into your exact problem before.
Debugging local builds#
A lot of things can generally go wrong when building an article with showyourwork!. The workflow will try its best to give you an informative error message, but if you can’t figure out what the problem is (or you don’t know how to fix it), consider the following tips:
Inspect the build logs. These live in .showyourwork/logs and contain a lot of the verbose output that’s suppressed from the terminal by default (see Logging).
Run
showyourwork clean
or, if that doesn’t help,showyourwork clean --force
. These commands remove all build output, which could help resolve issues caused by builds that are interrupted by an error or when the user cancels them halfway. If you don’t want to lose your output, you could also try just deleting the temporary .showyourwork directory (instead of running theclean
command), which removes the cache and forces re-evaluation of the build graph.Identify which part of the workflow is causing the problem. Is it during the run of a particular figure script? Consider adding a
breakpoint
in your code to enable interactive debugging. Or is the problem specific to the LaTeX build step? LaTeX errors, in particular, can be extremely cryptic. Inspect the .showyourwork/logs/tectonic.log file for details. Consider commenting out portions of your manuscript to identify which part is causing the problem.If one of your figures is causing a new error, it can be helpful to temporarily bypass it by placing the old figure output (e.g., the .pdf file) in the
src/static
directory and commenting out the\script
command in the TeX file. This causes showyourwork! to treat the figure as static, preventing it from trying to re-generate it the next time you runshowyourwork
.Sometimes, cryptic errors can occur if you’ve made a mistake in the config file. Certain settings require a very specific YAML syntax, so please check The showyourwork.yml config file to ensure you’ve provided, e.g., the
datasets
information correctly.Make sure you are using the latest version of showyourwork!, as your error could be due to a bug we have since fixed! You can always upgrade to the latest version by running
pip install -U showyourwork
.Check the GitHub Issues to see if others have run into the same issue. It’s also worth checking out the closed issues for ones that have already been resolved!
If all else fails, feel free to raise a new issue, and we will do our best to get back to you with suggestions promptly.
Debugging remote builds#
If your article build works locally but fails on GitHub Actions, a few different things could be going on.
A common cause is you forgot to push a particular script to the remote, so make sure you don’t have any unstaged changes, and that your .gitignore files aren’t preventing you from committing necessary files.
It’s also useful to make sure you’ve provided all the necessary repository secrets, such as
SANDBOX_TOKEN
, which is used to access the Zenodo Sandbox API to download files from the remote cache. See Zenodo integration for details. If you’re reproducing someone else’s article and don’t have access to their API token, you can either setrun_cache_rules_on_ci
totrue
in the config file to allow running cached rules on GitHub Actions (see The showyourwork.yml config file), or you can switch to a cache deposit you have read/write access to. To do this, delete the zenodo.yml file at the root of the repository and runshowyourwork cache create
(after making sure you’ve defined the$SANDBOX_TOKEN
environment variable; see Zenodo integration). Run the workflow locally to populate the cache, then commit and push your results. If you’ve provided theSANDBOX_TOKEN
repository secret on GitHub (see Zenodo integration), the workflow should now be able to access the Sandbox cache.A different issue potentially affecting remote builds is hysteresis in your local workflow: for example, you may have built your article successfully, then deleted one of the scripts needed to generate a figure. The next time you build your article, the build could succeed since the figure output is present and there are no new instructions specifying how to build it (because the input file was deleted). On the remote, however, where the output file does not exist, you will get a build failure. You can avoid these sorts of issues by setting
require_inputs
totrue
in the config file (see The showyourwork.yml config file), although in recent versions of showyourwork! that should already be the default.Another issue has to do with the fact that showyourwork! uses conda environments instead of actual containers or virtual machines. Conda environments are not always free of contamination from packages installed in the global scope. For instance, one can import a package from outside the workflow’s isolated conda environment by tinkering with the
$PATH
environment variable within a Python script. Such a workflow could succeed locally but fail on the remote, where that package may not be present in the global environment. This can especially be a problem if you are using tools, packages, or software that are not managed by conda. In that case, make sure you are also installing them and making them available to the GitHub Actions runner. An example of this is covered below in Rendering LaTeX in matplotlib, wherematplotlib
may require access to a full LaTeX installation to render LaTeX strings. Such builds will fail on the remote unless LaTeX is manually installed in the workflow YAML file.Finally, one can mimic the behavior of the remote build by setting the
CI=true
environment variable prior to runningshowyourwork
. Depending on the nature of the error, it could also make sense to look into tools that allow direct interaction with the runner on GitHub Actions, such as action-tmate.
IncompleteFilesException#
If you run your workflow and interrupt it (e.g., by hitting Ctrl + C
) while
a rule is being executed, or if an error in your code causes the workflow to
fail, you may end up with a situation where Snakemake marks some of your output
files as “incomplete”. This is useful in cases where the interruption may have
corrupted those files. Snakemake tries to be conservative about this, and requires
users to either re-run the problematic rule or manually mark the files as
incomplete. When this happens, showyourwork
tells the user:
If you are sure that certain files are not incomplete, mark them as complete with
showyourwork build --cleanup-metadata <filenames>
To re-generate the files rerun showyourwork build with the --rerun-incomplete flag.
Sometimes, however, the --cleanup-metadata
argument does not successfully
clean up the incomplete files. This may be due to either an issue with Snakemake
(see
here
and here) or an issue
with showyourwork!
(see here); we’re
still looking into how to fix this.
If you find yourself stuck trying to cleanup the metadata (in cases where you would like to keep your current output files), you can try manually deleting the folder .snakemake/incomplete, which keeps track of that metadata. Alternatively, you can manually delete all of the problematic output files, which will trigger a re-run of the corresponding rule.
Issues due to git#
The showyourwork! workflow relies heavily on command line calls to git
.
The pipeline is tested for git>=2.24.0
, so certain issues may arise with
older versions. For instance, prior to version 0.3.0.dev9
of showyourwork
,
the current git branch was determined by running git branch --show-current
,
an option that was only introduced in git==2.22.0
and led to strange
behavior on platforms running older versions of git
. This issue has since
been addressed, but there may be others that you might encounter if your
git
is significantly out of date.
You can always check which version of git
you are using by
running git --version
, and upgrade it if needed using homebrew
(MacOS)
or apt-get
(Linux).
Permissions errors in GitHub Actions#
If you try to build a showyourwork! article from a repository fork
on GitHub Actions, you may run into the following error when the action
attempts to push the results to the -pdf
branch:
Uploading output
/tmp/tmp.KORuhtnUA7
Switched to a new branch 'main-pdf'
[main-pdf (root-commit) 224ecfd] force-push article output
2 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 arxiv.tar.gz
create mode 100644
remote: Permission to $USER/$REPO.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/$USER/$REPO/': The requested URL returned error: 403
This happens because the default GitHub Actions permissions for the GITHUB_TOKEN
secret are set to restricted
for repository forks. To get the build to work,
go to
https://github.com/$USER/$REPO/settings/actions
and change the permissions to permissive
:
Rendering LaTeX in matplotlib#
When plotting with matplotlib
, if you run into errors that look like
FileNotFoundError: [Errno 2] No such file or directory: 'latex'
or
RuntimeError: Failed to process string with tex because latex could not be found
you are probably missing a proper latex
installation. Recall that showyourwork!
uses tectonic
to build your article, which is not compatible with matplotlib
.
Instead, you’ll have to install a separate TeX distribution, such as TeXLive or MiKTeX.
The same applies to runs on GitHub actions.
The simplest workaround is to disable LaTeX rendering in matplotlib
:
import matplotlib.pyplot as plt
plt.rcParams.update({"text.usetex": False})
Math-mode strings can still be parsed using the built-in matplotlib
renderer,
and in most cases this will do what you need. In some cases, however, the built-in
renderer may not cut it. If you really need a proper LaTeX installation, you’ll
have to do a bit of extra work to get your build to pass on GitHub Actions.
First, add the following step to the build.yml and build-pull-request.yml
workflows in your .github/workflows folder, just before the showyourwork!
build
step:
- name: Install TinyTex for matplotlib LaTeX rendering
id: tinytex
shell: bash -l {0}
run: |
wget -qO- "https://yihui.org/tinytex/install-bin-unix.sh" | sh
sudo ~/bin/tlmgr install type1cm cm-super
This will install TinyTex, a
very lightweight TeX distribution that should provide everything you need. Note
that this step also installs the type1cm
and cm-super
LaTeX packages,
which may be required by matplotlib
. You can specify additional packages
in the same line if needed.
Then, in order for matplotlib
to execute latex
, the ~/bin path needs to
be in the system $PATH
. This variable gets overwritten when running scripts inside isolated
conda
environments (as showyourwork! does), so you’ll need to add ~bin
to the $PATH
within your Python script. Therefore, add the
following bit of boilerplate to the top of any scripts that require LaTeX parsing:
import os
from pathlib import Path
os.environ["PATH"] += os.pathsep + str(Path.home() / "bin")
To save some typing, you could instead add this boilerplate to the src/scripts/paths.py file so that these commands get executed whenever that file is imported into your scripts.
Using paths.py within subdirectories#
For complicated workflows, you may wish to organize your scripts directory into subdirectories.
However, this creates a problem with using the paths
module, since import paths
relies on paths.py being in the same directory as your scripts.
There is a simple workaround for this issue.
Simply add showyourwork
as a dependency in environment.yml, and add the following to the top of your scripts:
from showyourwork.paths import user as Paths
# instantiate the paths
paths = Paths()
You can now use paths.data
, paths.figures
, etc. as usual.
Note that if you decide to take this approach, we recommend that you pin the version of showyourwork
in environment.yml to the same version specified in the showyourwork.yml config file. See this comment for a brief discussion.
Using LaTeX fonts in matplotlib without installing LaTeX#
If you just want matplotlib
to use Computer Modern fonts so that the font in your plots matches the font in your manuscript, you can accomplish this without the full LaTeX installation described above.
Just add the following lines to src/scripts/matplotlibrc:
# set font to match LaTeX's Computer Modern
font.family: serif
font.serif: cmr10
mathtext.fontset: cm
axes.formatter.use_mathtext: True # needed when using cm=cmr10 for normal text
Using LaTeX Workshop in VSCode#
If you edit and build your articles in VSCode, you need to specify some settings so that VSCode knows to use showyourwork! to build your document. You can do this by creating (or editing) a workspace-specific settings file, .vscode/settings.json, in the root directory of your repo. At minimum, you should add the following lines:
{
# other settings here
"latex-workshop.latex.external.build.command": "showyourwork",
"latex-workshop.latex.external.build.args": [],
"latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%",
"latex-workshop.view.pdf.viewer": "tab"
}
This enables you to build the document using LaTeX Workshop: Build LaTeX project
in the command palette.
Note that the final line tells LaTeX Workshop to open your article pdf in a VSCode tab.
Feel free to change tab
to browser
if you would rather LaTeX Workshop open your article in a browser tab.
If you also want to use LaTeX Workshop’s AutoBuild on save (or on file change), you can add the following lines to the settings file:
{
# other settings here
"latex-workshop.latex.recipe.default": "showyourwork",
"latex-workshop.latex.recipes": [
{
"name": "showyourwork",
"tools": [
"showyourwork"
]
}
],
"latex-workshop.latex.tools": [
{
"name": "showyourwork",
"command": "showyourwork",
"args": [],
"env": {}
},
]
}
Errors in the conda_env.py module#
Version 0.3.1
of showyourwork! introduced a change to the
way showyourwork
versions are specified in the showyourwork.yml config
file. Previously, the version:
keyword accepted a string corresponding
to a version number, a GitHub ref, or a local path to a showyourwork
installation. As of 0.3.1
, the workflow accepts mappings of the form
pip: <version-on-PyPI>
and fork: <fork-name>
, in addition to the
old syntax (in which the workflow infers whether the provided value is a
version number, a ref, or a path). Even though this is backwards-compatible
in that the old syntax is still allowed, repositories that use the new syntax
cannot be built using older versions of showyourwork
(which will fail
when trying to parse the new syntax of the version:
key). Users may run
into errors that look something like this:
File "/home/runner/.local/bin/showyourwork", line 8, in <module>
sys.exit(entry_point())
File "/usr/lib/python3/dist-packages/click/core.py", line 764, in __call__
return self.main(*args, **kwargs)
File "/usr/lib/python3/dist-packages/click/core.py", line 717, in main
rv = self.invoke(ctx)
File "/usr/lib/python3/dist-packages/click/core.py", line 1137, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/lib/python3/dist-packages/click/core.py", line 956, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/usr/lib/python3/dist-packages/click/core.py", line 555, in invoke
return callback(*args, **kwargs)
File "/home/runner/.local/lib/python3.8/site-packages/showyourwork/cli/main.py", line 92, in build
commands.preprocess()
File "/home/runner/.local/lib/python3.8/site-packages/showyourwork/cli/commands/preprocess.py", line 16, in preprocess
result = run_in_env(command, check=False)
File "/home/runner/.local/lib/python3.8/site-packages/showyourwork/cli/conda_env.py", line 83, in run_in_env
elif re.match(r"(?:(/d+/.[./d]*/d+))", syw_spec):
File "/usr/lib/python3.8/re.py", line 191, in match
return _compile(pattern, flags).match(string)
TypeError: expected string or bytes-like object
This error can be fixed by simply upgrading your local installation of showyourwork
:
pip install -U showyourwork
Figures not getting generated#
If you are getting LaTeX build errors due to a figure not being present, the first
thing you should do is check the build logs in .showyourwork/logs/showyourwork.log.
Did the figure script get executed? If so, perhaps the figure was saved to the incorrect
path (did you remember to save it to src/tex/figures? See paths.py). If the figure script is not
being executed, check if you included the appropriate \script
command in the figure
environment in your manuscript (see LaTeX stuff). One other common pitfall is either a
missing figure \label
or a duplicate one. Figure nodes in the article graph are
labeled according to the figure \label
, so defining the same label for two different
figures means only one will be indexed by showyourwork!
Missing LaTeX class files#
If your manuscript uses a custom class file that tectonic
isn’t able to automatically
download (like those required by some journals) you may run into a LaTeX compilation
error like this one:
Failed to compile manuscript. Perhaps you forgot to `\usepackage{showyourwork}`?
For more information, check out the log file:
.showyourwork/logs/tectonic.log
The errors printed to the terminal are often cryptic, but if we open the log file linked above, we can see that the issue is due to a missing class file (in this case, aastex631.cls):
**
(ms.tex
LaTeX2e <2020-02-02> patch level 5
L3 programming layer <2020-03-06>
! LaTeX Error: File `aastex631.cls' not found.
Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: cls)
Enter file name:
Prior to version 0.3.1
, showyourwork shipped with class files for some of the
major astronomy journals (ApJ, A&A, and MNRAS), so if you were using any of those
you were unlikely to run into this error. However, for various reasons
(such as issues with long-term maintenance of these classes and
better interfacing with Overleaf) we decided it was
best to stop automatically providing these class files as of version 0.3.1
.
Therefore, articles that define a version of showyourwork greater than or equal
to 0.3.1
in showyourwork.yml must provide all the necessary class and auxiliary
files in src/tex as git
-tracked files. This applies to both articles created using
showyourwork setup
and articles for which the version in showyourwork.yml is manually
upgraded. (It does not apply to articles with older version specs, even if you upgrade your
local installation of showyourwork.)
So, if you run into this error, we recommend you download all required files directly from
the journal and include them (making sure to git add
them) in your src/tex folder.