Migrating from previous versions
Migrating from previous versions#
Version 0.3.0
introduced several breaking changes, so repositories dependent on previous
versions need to be modified if you update showyourwork!. This page contains a list of
things you’ll want to do when migrating over.
Note
If you’re running into issues while migrating from a previous version of showyourwork!, or if the steps below are too complicated, feel free to open an issue on the showyourwork! GitHub page and we’ll help you with the migration!
Note
If you’re using an older version of showyourwork! and things are working just fine for your article, there’s no need to upgrade! Your article will continue to work and can be reproduced by others. Previous versions of showyourwork! will remain on GitHub and their documentation on readthedocs will persist. The downside is that you won’t benefit from newer functionality or bugfixes (in case you find issues with showyourwork!).
First, install showyourwork! locally (see Installation). Prior to
0.3.0
, showyourwork! was entirely contained in a submodule located in the article repository itself. It is now a Python package that can easily be installed withpip
.Delete the
showyourwork
folder at the top level of your repository. Since this is a git submodule, you should also delete everything under[submodule "showyourwork"]
in the.gitmodules
file. If that file is otherwise empty, you can delete it as well.Remove the boilerplate code from the top-level
Snakefile
. Unless you added custom Snakemake rules for your workflow, this file should now be empty by default. The newer versions of showyourwork! import this Snakefile into the main workflow file (rather than the other way around), so no user-side boilerplate code is needed.Delete the
Makefile
. The new version of showyourwork! no longer relies onmake
. Articles should now be compiled by running theshowyourwork
command line tool.Delete
.github/workflows/showyourwork.yml
. Copy over the workflow files from the example repository. Copy over any custom code from your previous workflow file (if you manually added/changed stuff) to the newbuild*.yml
files. Since the workflow files changed, you might have to update the workflow badge in yourREADME.md
file (i.e., replace occurrences ofshowyourwork.yml
withbuild.yml
).Create a folder called
src/tex
and move your manuscript (e.g.,ms.tex
), bibliography (e.g.,bib.bib
), and any other custom LaTeX files into it. Hint: to preserve your git history for those files, usegit mv
instead ofmv
.Create a folder called
src/tex/figures
and add a.gitignore
file inside. Copy its contents from the example repository. This folder will contain all the figure outputs (e.g.,*.pdf
,*.png
, etc.), so nothing in this folder should be tracked by git.Create a folder called
src/tex/output
and add a.gitignore
file inside. Copy its contents from the example repository. This folder will contain any other output generated by your workflow and included in your TeX file, so nothing in this folder should be tracked by git.Add a file called
showyourwork.sty
tosrc/tex
. You can copy it over from the example repository. This is the new showyourwork! LaTeX style file.Read about changes to the way showyourwork! parses LaTeX at LaTeX stuff. The two big changes are that you must now explicitly import the
showyourwork
style file (see above) using\usepackage{showyourwork}
and that relationships beteween figure scripts and figure files are no longer inferred from the figure\label
. Instead, users should explicitly provide the path to the script (relative tosrc/scripts
) that generates figures inside afigure
environment via the\script
command. Edit your figure environments in your tex file accordingly; see LaTeX stuff for details, as there are a few other subtleties.Rename the
src/figures
directory tosrc/scripts
. This folder should still contain your figure scripts–just its naming convention in showyourwork! changed. Hint: to preserve your git history across this rename, dogit mv src/figures src/scripts
instead of a simplemv
.Add a file called
paths.py
tosrc/scripts
. You can copy it over from the example repository. This file contains useful absolute paths to the various directories in your repository (see below).Given the new directory structure (see above), figure scripts (in
src/scripts
) must now output figure files into thesrc/tex/figures
directory. You will therefore have to edit your scripts to ensure they save figure outputs to that directory. Importantly, you should ensure your scripts will save the figures to the correct directory regardless of where they are executed from. The new version of showyourwork! executes scripts from the top-level directory of your repository, so any relative paths in your scripts are relative to the root of your repository. To make things easier, we recommend you use the paths provided in thepaths.py
file. For example, to save a figure calledfigure.pdf
to the correct output directory, import thepaths
module and run (e.g.)fig.savefig(paths.figures / "figure.pdf")
. The same applies to datasets; a dataset called located atsrc/data/dataset.txt
can be accessed aspaths.data / "dataset.txt"
. Read more about thepaths.py
file at Repository layout.Finally, the syntax for the
showyourwork.yml
config file changed, particularly with regards tozenodo
datasets. Users should also now provide an explicit version of showyourwork! using theversion
key. Please see The showyourwork.yml config file for details.
You can see an example diff of a repository that went through this upgrade here. If you run into any issues, have questions, or would like help with the upgrade, please create an issue on GitHub and we’ll be more than happy to help!