.. raw:: html

  <style>
    section p {
      margin-bottom: 0px;
    }
  </style>

The ``showyourwork.yml`` file
=============================

This is the configuration file for ``showyourwork``, allowing you to
customize several aspects of the workflow. Below is a list of all
available options.


``arxiv_tarball_exclude``
^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``list``

**Description:** List of of files/paths to exclude from the arXiv tarball.
By default, ``showyourwork`` will never include ``python`` scripts, ``matplotlibrc``
config files, ``python`` and ``showyourwork`` temporaries, or ``.gitignore``
files in the tarball. It will also automatically exclude datasets that are
uploaded to/downloaded from Zenodo. This option is useful if there are other
files in your repository -- such as static datasets or other kinds of scripts --
that don't need to be included in the tarball. Note that glob syntax is allowed,
and all paths should be relative to the root of your repository.

**Required:** no

**Default:** ``[]``

**Example:**

.. code-block:: yaml

  arxiv_tarball_exclude:
    - src/data/dataset.dat
    - src/ms.bib
    - src/**/*.sh


``CI``
^^^^^^

**Type:** ``bool``

**Description:** Flag indicating whether or not this is a GitHub Actions continuous
integration (CI) build. This is set automatically, but can be overridden here
for debugging purposes.

**Required:** no

**Default:** (inferred automatically)

**Example:**

.. code-block:: yaml

  CI: false


``dependencies``
^^^^^^^^^^^^^^^^

**Type:** ``list``

**Description:** List of dependencies for each script. Each entry should be 
the path to a script (either a figure script or the TeX manuscript itself) 
relative to the repository root. Following each entry, provide a list of 
all files on which the script depends. These dependencies may either be
static (such as helper scripts) or programmatically generated (such as
datsets downloaded from Zenodo). In the latter case, instructions on how
to generate them must be provided elsewhere (either via the ``zenodo`` key
below or via a custom ``rule`` in the ``Snakefile``). In both cases, changes
to the dependency will result in a re-run of the section of the workflow that
executes the script.

**Required:** no

**Default:** ``[]``

**Example:**
Tell ``showyourwork`` that the figure script ``my_figure.py`` depends on
a helper script called ``helper_script.py``:

.. code-block:: yaml

  dependencies:
    src/figures/my_figure.py:
      - src/figures/utils/helper_script.py

See `script dependencies <custom.html#script-dependencies>`_. You can also
specify a dependency on a programmatically-generated file:

.. code-block:: yaml

  dependencies:
    src/figures/fibonacci.py:
        - src/data/fibonacci.dat

See `dataset dependencies <custom.html#dataset-dependencies>`_. Finally,
dependencies of the manuscript file are also allowed:

.. code-block:: yaml

  dependencies:
    src/ms.tex:
        - src/answer.tex

See `custom manuscript dependencies <custom.html#custom-manuscript-dependencies>`_.


``figexts``
^^^^^^^^^^^

**Type:** ``list``

**Description:** List of recognized figure extensions. 

**Required:** no

**Default:** ``[pdf, png, eps, jpg, jpeg, gif, svg, tiff]``

**Example:**

.. code-block:: yaml

  figexts:
    - pdf
    - png


``ms``
^^^^^^

**Type:** ``str``

**Description:** Path to the main TeX manuscript. Change this if you'd prefer to
name your manuscript something other than ``src/ms.tex``. Note that you should still
keep it in the ``src/`` directory. Note also that the compiled PDF will still be named
``ms.pdf`` regardless of this setting.

**Required:** no

**Default:** ``src/ms.tex``

**Example:**

.. code-block:: yaml

  ms: src/article.tex

See `custom manuscript name <custom.html#custom-manuscript-name>`_.


.. _scripts:

``scripts``
^^^^^^^^^^^

**Type:** ``list``

**Description:** List of script extensions and instructions on how to execute 
them to generate figures. By default, ``showyourwork`` expects figure files to
be generated by executing figure scripts with ``python``. You can add custom
rules here to produce figures from scripts with other extensions, or change
the behavior for executing ``python`` scripts (such as adding command line
options, for instance). Each entry under ``scripts`` should be a file extension,
and under each one should be a string specifying how to generate the figure file
``{figure}`` from the figure script ``{script}``. These two strings are special
placeholders recognized by ``showyourwork`` -- they resolve to the names of the
two files, relative to the ``src/figures`` directory. Note that the command you specify 
here will always be executed from within the ``src/figures`` directory.

**Required:** no

**Default:** ``[]``

**Example:**
We can tell ``showyourwork`` how to generate figures from Graphviz ``.gv``
files as follows:

.. code-block:: yaml

  scripts:
    gv:
      dot -Tpdf {script} > {figure}

See `non-Python figure scripts <custom.html#non-python-figure-scripts>`_.


``tectonic_latest``
^^^^^^^^^^^^^^^^^^^

**Type:** ``bool``

**Description:** Use the latest version of ``tectonic`` (built from source) instead
of the most recent stable version? You shouldn't normally have to edit this entry.

**Required:** no

**Default:** ``false``

**Example:**

.. code-block:: yaml

  tectonic_latest: true


``tectonic_os``
^^^^^^^^^^^^^^^

**Type:** ``str``

**Description:** Operating system used for choosing which ``tectonic``
binary to install (only if ``tectonic_latest`` is ``true``). 
This is usually determined automatically, but can be
overridden. Options are ``x86_64-unknown-linux-gnu``, ``x86_64-apple-darwin``,
or ``x86_64-pc-windows-msvc``.

**Required:** no

**Default:** (inferred automatically)

**Example:**

.. code-block:: yaml

  tectonic_os: x86_64-apple-darwin


``verbose``
^^^^^^^^^^^

**Type:** ``bool``

**Description:** Enable verbose output? Useful for debugging runs.

**Required:** no

**Default:** ``false``

**Example:**

.. code-block:: yaml

  verbose: true


``zenodo``
^^^^^^^^^^

**Type:** ``list``

**Description:** A list of datasets to be download from and/or uploaded to
Zenodo. Each entry should be the path to a dataset, followed by keys
specifying information about the Zenodo deposit. These keys depend on the use
case. If the deposit already exists (i.e., it was uploaded manually), then
users need only specify the deposit :ref:`id <zenodo.dataset.id>`. If the
deposit does not exist, and users would like ``showyourwork`` to upload it/download
it from Zenodo, they should specify the following keys (most of which are optional):
:ref:`script <zenodo.dataset.script>`,
:ref:`title <zenodo.dataset.title>`,
:ref:`description <zenodo.dataset.description>`,
and :ref:`creators <zenodo.dataset.creators>`.
Finally, if the deposit is a tarball consisting of many datasets, users should
also specify the tarball :ref:`contents <zenodo.dataset.contents>`.
In all cases, a :ref:`sandbox <zenodo.dataset.sandbox>` and a 
:ref:`token_name <zenodo.dataset.token_name>` key are also accepted.

.. note::

    If an ``id`` is not provided, ``showyourwork`` will attempt to generate
    the dataset by executing the ``script``, but only when running locally. 
    If successful, it will upload
    the file to Zenodo. As long as the ``script`` generating the dataset does
    not change (and the dataset is not deleted), the ``script`` will not be
    re-run.
    When running on GitHub Actions, however, the script will **never** be
    executed; instead, ``showyourwork`` will always download the dataset from
    Zenodo. The idea here is to prevent the workflow from executing expensive
    operations on the cloud. In order for this to work, however, a deposit must
    exist, so you must run your workflow at least once locally before pushing
    the changes to GitHub.

**Required:** no

**Default:** ``[]``

**Example:**
See `dataset dependencies <custom.html#dataset-dependencies>`_,
`simulation dependencies <custom.html#simulation-dependencies>`_,
`dependency tarballs <custom.html#dependency-tarballs>`_,
and
`dependency tarballs (advanced) <custom.html#dependency-tarballs-advanced>`_.


.. _zenodo.dataset.contents:

``zenodo.<dataset>.contents``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``list``

**Description:** If ``<dataset>`` is a ``.tar.gz`` file, users should provide
a list of all the files to include in this tarball, which will be automatically
generated by ``showyourwork``. Instructions for generating these individual files
should be provided separately, either via the :ref:`script <zenodo.dataset.script>`
key or via a custom ``rule`` in the ``Snakefile``.

**Required:** yes, but only if ``<dataset>`` is a ``.tar.gz`` tarball.

**Default:**

**Example:**
See `dependency tarballs <custom.html#dependency-tarballs>`_.


.. _zenodo.dataset.creators:

``zenodo.<dataset>.creators``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``list``

**Description:** A list of creators to be listed on the Zenodo record and associated
with the record DOI.

**Required:** no

**Default:** The GitHub username of the current user

**Example:**
See `simulation dependencies <custom.html#simulation-dependencies>`_.


.. _zenodo.dataset.description:

``zenodo.<dataset>.description``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``str``

**Description:** A detailed description of the file, how it was generated, and
how it should be used, to be displayed on the Zenodo record page.

**Required:** no

**Default:** ``"File uploaded from <repository-name>"``

**Example:**
See `simulation dependencies <custom.html#simulation-dependencies>`_.


.. _zenodo.dataset.id:

``zenodo.<dataset>.id``
^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``int``

**Description:** The ID of a pre-existing Zenodo deposit. This ID is the
number in the URL of a Zenodo record, i.e., ``5187276`` for
`<https://zenodo.org/record/5187276>`_. ``showyourwork`` will attempt to
download the dataset ``<dataset>`` from this record using ``curl``.

**Required:** yes, but only if the record exists already

**Default:** 

**Example:**
The following snippet

.. code-block:: yaml

  zenodo:
    - src/data/fibonacci.dat:
        id: 5187276

tells ``showyourwork`` to download the file ``fibonacci.dat`` from
the Zenodo deposit at `<https://zenodo.org/record/5187276>`_.

See `dataset dependencies <custom.html#dataset-dependencies>`_.


.. _zenodo.dataset.sandbox:

``zenodo.<dataset>.sandbox``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``bool``

**Description:** A flag telling ``showyourwork`` whether to use the Zenodo 
Sandbox service. This service behaves identically to Zenodo, but files hosted
here are wiped on a random basis, so it is intended only for debugging and
development purposes. This flag should be set to ``false`` when development
is complete.

**Required:** no

**Default:** ``false``

**Example:**
See `simulation dependencies <custom.html#simulation-dependencies>`_.


.. _zenodo.dataset.script:

``zenodo.<dataset>.script``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``str``

**Description:** The path to the ``python`` script that generates the ``<dataset>``
(or, if ``<dataset>`` is a tarball, the script that generates its contents).
Note that this *must* be a ``python`` script, even if custom script instructions
are provided via the :ref:`scripts <scripts>` key. To define custom rules for
generating the dataset, see the 
`dependency tarballs (advanced) <custom.html#dependency-tarballs-advanced>`_ example.

**Required:** yes, unless a custom ``rule`` is provided in the ``Snakefile``

**Default:**

**Example:**
See `simulation dependencies <custom.html#simulation-dependencies>`_.


.. _zenodo.dataset.title:

``zenodo.<dataset>.title``
^^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``str``

**Description:** The title of the Zenodo deposit.

**Required:** no

**Default:** ``"<repository-name>:<dataset>"``

**Example:**
See `simulation dependencies <custom.html#simulation-dependencies>`_.


.. _zenodo.dataset.token_name:

``zenodo.<dataset>.token_name``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Type:** ``str``

**Description:** The name of the environment variable containing the
Zenodo access token (or the Zenodo sandbox access token, if 
:ref:`sandbox <zenodo.dataset.sandbox>` is ``true``).
To obtain this token, create a `Zenodo account <https://zenodo.org/signup>`_ 
(if you don't have one already) and
generate a `personal access token <https://zenodo.org/account/settings/applications/tokens/new/>`_.
Make sure to give it at least ``deposit:actions`` and ``deposit:write`` scopes, and store it somewhere
safe. Then, assign your token to an environment variable called ``ZENODO_TOKEN`` (or whatever
you set ``token_name`` to). I export mine from within my ``.zshrc`` or ``.bashrc`` config file so that 
it's always available in all terminals.
Finally, to give ``showyourwork`` access to Zenodo from GitHub Actions, create a 
`repository secret <https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository>`_
in your GitHub repository with the same name (i.e., ``ZENODO_TOKEN``) and set its value equal to your Zenodo token.

.. warning::

    Never include your personal access tokens in any files committed to GitHub!


**Required:** no

**Default:** ``ZENODO_TOKEN``

**Example:**
See `simulation dependencies <custom.html#simulation-dependencies>`_.