Repository layout

If you created your repository from the showyourwork template, 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 .github/workflows/showyourwork.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
    submodules: recursive

and run the custom showyourwork-action to build the article:

- name: Build the article PDF
  id: build
  uses: ./showyourwork/showyourwork-action

You can add other steps to this workflow or configure the action settings (see The showyourwork GitHub action), but most users shouldn’t have to tweak this file. Check out the GitHub documentation for more information on configuring workflows.

The showyourwork submodule

This is a Git submodule that contains the showyourwork workflow, which manages the entire build process for your article. You should not edit this submodule directly. However, you can update it to the latest version of showyourwork by running

git submodule update --remote

in the top level of your repository, or switch to a specific version of the workflow (say v0.1.0) by running

pushd showyourwork
git fetch --all --tags
git checkout tags/v0.1.0
popd

again in the top level of your repository. Make sure to push your changes to the remote afterwards. Check out Updating showyourwork for more information.

The src directory

This directory contains the source code for building your article. This includes the LaTeX manuscript, the bibliography file, and the scripts and supplementary files needed to produce all of the article figures. Figure scripts and auxiliary code should be placed in the figures directory and (small) datasets and committed figures (if absolutely necessary!) should be placed in the static directory. See below for details.

The figures directory

This directory should contain all of the scripts needed to produce the figures in your article. The names of these scripts should match the figure labels in the manuscript file (see here for details), although you can override this behavior by providing custom workflow rules (see Custom workflows). You can have other stuff in this directory as well (such as auxiliary scripts or procedurally-generated datasets).

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

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

The .gitmodules file simply tells git that the showyourwork directory is a submodule. You shouldn’t have to change anything in here.

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 Snakefile workflow

The Snakefile contains all of the instructions on how 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 should look something like this:

# Import the showyourwork module
module showyourwork:
    snakefile:
        "showyourwork/workflow/Snakefile"
    config:
        config

# Use all default rules
use rule * from showyourwork

All this is doing is importing the showyourwork workflow (shipped within the git submodule in your repo) and then telling Snakemake to use all the rules in that workflow. You typically won’t want to remove any of these lines, but feel free to add whatever you’d like to your Snakefile. This might include rules 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 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 showyourwork.yml config file

This is the Snakemake config file for showyourwork, where you can customize several aspects of the build. Below is a list of all options along with their default values and a brief description of what they do:

# Enable verbose output during the build process?
verbose: true

# Recognized figure extensions
figexts:
  - pdf
  - png
  - eps
  - jpg
  - jpeg
  - gif
  - svg
  - tiff

# Paths to be excluded from the arxiv tarball generated on GitHub Actions
arxiv_tarball_exclude:
  - "**/*.py"
  - "**/matplotlibrc"
  - "**/.gitignore"

# Figure dependencies. Each entry should be the name of a figure script
# relative to the ``src/figuress`` directory. These entries, in turn,
# should contain a list of dependencies, relative to the same folder.
# For example, if the figure script ``src/figures/script.py`` requires a
# file ``src/figures/dataset.dat`` in order to run, you may specify that as
#
#   figure_dependencies:
#     script.py:
#       - dataset.dat
#
# These dependencies can also include rules to generate, upload, and/or
# download them from Zenodo. Please see the ``Custom workflows`` section
# of the documentation for more details.
figure_dependencies: