Repository layout#

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:

on:
  push:

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 a special workflow_run trigger activated on runs of this workflow. See below for details.

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) pull-request-<NUMBER>-pdf, where <NUMBER> is the number of the pull request. This workflow also posts a comment in the PR discussion with a link to the PDF for convenience.

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 static directory; and TeX files should be placed in the tex directory. 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 git.

The .gitignore files#

The .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 (.pdf, .png, .tiff, etc), LaTeX temporaries (.log, .aux, .blg, etc), or any kind of output. In some cases, it might make sense to include one of these files (say, a .png photograph that can’t be generated programatically from a script). To commit something that’s disallowed by a .gitignore file, just use the -f or --force option when adding the file to git.

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:

backend: agg

which tells 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 `data, figures, 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 .gitignore file in this directory prevents anything in it from being tracked by git, as all figures 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 tectonic 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:

\usepackage{showyourwork}

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 pdflatex or tectonic), things will still work, but you won’t benefit from any of the showyourwork functionality.

The environment.yml file#

The 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 (e.g., numpy and matplotlib). Feel free to manually add to this list (noting that packages that can only be installed via pip should be placed in the pip section). It’s recommended to either pin a specific version (i.e., matplotlib==3.3.4) or specify a minimum version (i.e., matplotlib>=3.0.0) for your packages. Just be aware that overconstrained requirements may break on other platforms (see this post), so you should probably only pin the direct dependencies of your project. If you alread have a conda environment for your project, you can export these direct dependencies – the ones that you explicitly installed in the enviornment – by running

conda env export --from-history | grep -v "^prefix: " > environment.yml

The grep command removes the line in the environment file with the absolute path to your conda environment, which probably won’t be useful to anyone else running your code!

The LICENSE file#

The 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#

The 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 Snakefile, such as instructions on how to build custom figures, to download datasets, etc; see Custom workflows. 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.