If you created your repository via showyourwork setup, it should have the following overall layout:
Click on each of the files or folders in the directory tree above to read more about them.
The build.yml file#
This is the configuration file for the workflow that builds your article on GitHub Actions. It instructs GitHub Actions to build the article every time a commit is pushed to the remote:
The workflow tells GitHub to checkout the repository:
- name: Checkout uses: actions/checkout@v2 with: fetch-depth: 0
and run the custom
showyourwork-action to build the article:
- name: Build the article PDF id: build uses: showyourwork/showyourwork-action@v1
You can add other steps to this workflow or configure the action settings (see The GitHub action), but most users shouldn’t have to tweak this file. Check out the GitHub documentation for more information on configuring workflows.
The build-pull-request.yml file#
The contents of this file are identical to those of The build.yml file, except this workflow
is triggered only on pull requests. The reason for separating this out is that pull
request builds need a little bit of post-processing, which we can accomplish with
workflow_run trigger activated on runs of this workflow. See below
The process-pull-request.yml file#
Pull request builds only get read access to the repository, so they can’t upload the
article PDF anywhere. Instead, they generate a workflow artifact. This workflow
runs whenever a pull request build completes successfully. It downloads the build
artifact and force-pushes the article PDF to a special branch called (by default)
<NUMBER> is the number of the pull request.
This workflow also posts a comment in the PR discussion with a link to the PDF
The src directory#
This directory contains the source code for building your article. This includes
the LaTeX manuscript, the bibliography file, and the scripts
needed to produce all of the article figures. Figure scripts and auxiliary
code should be placed in the
scripts directory; datasets should be
programmatically generated or downloaded into the
data directory; static
figures (if absolutely necessary!) should be placed in the
directory; and TeX files should be placed in the
See below for details.
The data directory#
This directory is included in the template as a convenience. It is meant to
house temporary (non-tracked) datasets, such as those downloaded from Zenodo
or programmatically generated by a pipeline script.
By default, nothing in this directory is tracked by
The .gitignore files#
.gitignore files prevent you from committing certain kinds of files.
You can add entries to these files, but you shouldn’t have to remove any.
In general, you should never commit figures (
LaTeX temporaries (
.blg, etc), or any kind of output.
In some cases, it might make sense to include one of these files (say, a
photograph that can’t be generated programatically from a script). To commit
something that’s disallowed by a
.gitignore file, just use the
option when adding the file to
The scripts directory#
This directory should contain all of the scripts needed to produce the figures and/or datasets used in the generation of your article.
The matplotlibrc config#
This is a
matplotlib configuration file
(see the matplotlib docs).
By default, it contains only a single instruction:
matplotlib to render figures using the non-interactive backend
agg. You can change this and add additional config options, but note that
if the figures are generated using an interactive backend, this will likely
cause the GitHub Action to fail!
The paths.py file#
This file is included as a convenience to make it easy for scripts to load and save files
from/to the correct directories. It defines variables such as
scripts, etc.; these are
pathlib.Path instances corresponding to the absolute
path to the directories of the same name in your repository.
As an example, the following code
import paths import numpy as np import matplotlib.pyplot as plt data = np.loadtxt(paths.data / "dataset.txt") fig = plt.figure() plt.plot(data) fig.savefig(paths.figures / "figure.pdf")
loads a dataset called
dataset.txt from the data directory, plots it,
and saves the figure as
figure.pdf in the figures directory.
All paths declared in the
paths module are absolute, so the above script will
work regardless of what directory it is executed from.
The static directory#
This directory is meant to house figure files that can’t be generated from scripts, such as photos, flowcharts, reproductions of figures in other papers, etc. If you place your figure in here, showyourwork! will know not to try to generate it from any script.
The tex directory#
This is the directory containing the TeX manuscript, your bibliography, and any
other auxiliary files used in building the article PDF, such as custom class
files or TeX style sheets. The contents of this folder can be synced to/from
an Overleaf project (see Overleaf integration). The subfolder
figures (see below)
contains the actual figure files to be included in the article build.
The figures directory#
This directory contains the figure output (the files generated by the figure
scripts) that gets included in your final article PDF. The
in this directory prevents anything in it from being tracked by
all figures should be programmatically generated on the fly.
The output directory#
This directory contains any other output (generated by non-figure
scripts) that you’d like to include in your final article PDF. The
in this directory prevents anything in it from being tracked by
all output should be programmatically generated on the fly.
The bib.bib bibliography#
This is an optional LaTeX/BibTeX bibliography file. Feel free to delete or rename it if needed.
The ms.tex manuscript#
This is your manuscript file. By default, it’s a AASTeX v6.3.1
article file with a placeholder title, abstract, and introduction. Feel free to
change the article class to whatever you’d like, although you may have to include
(and commit) the
.sty stylesheet if it’s not in the standard TeXLive distribution.
You can also import whatever packages you want in
ms.tex – the
typesetting system will automatically download and install them when building
your article. Note that you can also rename this file to something else, as
long as you edit the corresponding setting (see The showyourwork.yml config file).
The showyourwork.sty file#
This is the showyourwork! TeX style sheet, which you should always include in your manuscript:
If you peek inside, there’s not much there: it’s a placeholder stylesheet that
imports all the showyourwork! functionality from elsewhere if the article
is built as part of the showyourwork! workflow. If you compile your article
with a standard TeX compiler (such as
tectonic), things will
still work, but you won’t benefit from any of the showyourwork functionality.
The environment.yml file#
environment.yml file specifies all of the
conda packages needed to
build your article. You can read more about environment files
in the conda docs.
By default, only the bare minimum specs are included
matplotlib). Feel free to manually add to this list
(noting that packages that can only be installed via
pip should be placed in
pip section). For packages listed under
dependencies, it is highly
recommended that users specify explict channels and pin exact versions, e.g.:
dependencies: - conda-forge::python=3.9
pip dependencies, users should also pin exact versions, e.g.:
- pip: - matplotlib==3.3.4
Note that overconstrained requirements may break the installation on other platforms
(see this post),
so users should consider only pinning the direct dependencies of their project.
conda environment already exists for a project, one can export
these direct dependencies – the ones whose installation was explicitly requested in the enviornment –
conda env export --from-history | grep -v "^prefix: " > environment.yml
grep command removes the line in the environment file with the absolute path
The LICENSE file#
LICENSE included in your repository is by default the MIT open-source
license. Feel free to change this to whatever license you prefer, although we
strongly recommend you to keep everything open source and free for others to
modify and adapt into their own work!
The README.md file#
You should include a description of your repository here. Keep the badges at the top, as these provide easy access to the compiled article and the build logs. Feel free to remove or change the logo, though!
The showyourwork.yml config file#
This is the Snakemake config file for showyourwork!, where you can customize several aspects of the build. For detailed information on this file, see the showyourwork.yml file.
The Snakefile workflow#
Snakefile contains custom instructions to build your article
from the files in your repository. If you’re not familiar with the Snakemake
workflow management system, read up on it here.
By default, the
Snakefile is empty: showyourwork! takes care of everything
for you. For custom workflows, you can add rules to your
as instructions on how to build custom figures, to download datasets, etc.
Note, finally, that this file is written in a language that’s a straightforward
superset of Python, so any regular Python commands and syntax is valid in it.
The zenodo.yml config file#
This is a config file used to store Zenodo caching information. This file is entirely managed by showyourwork!, so users should not edit it manually.