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 Makefile
¶
This is a standard Unix Makefile, enabling you to type make
to build the article.
You shouldn’t have to edit anything in here.
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
# Provide a list of files, one item per line preceded by a - ; glob
# syntax allowed. Paths are relative to the root of the repo.
arxiv_tarball_exclude:
# Script dependencies. Each entry should be the name of a Python script
# relative to the root of the repo. These entries, in turn,
# should contain a list of dependencies, relative to the same folder.
dependencies:
# Zenodo metadata. This should be a list of dataset names relative to the
# root of the repo. Each one should contain either a Zenodo ``id``
# for an existing deposit or instructions on how to generate and upload
# a new deposit. Please see the documentation on `Custom workflows` for
# more information.
zenodo: