showyourwork!

https://show-your.work/en/latest/
Admin
showyourwork! is a workflow management tool for open source scientific articles that automates...
Tokens:38,089
Snippets:611
Trust Score:5.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Display setup help

Source: https://show-your.work/en/latest/cli

View the command-line interface help and available options for the setup command.

```bash
showyourwork setup --help
```

--------------------------------

### Repository setup prompt

Source: https://show-your.work/en/latest/quickstart

The initial prompt displayed by the setup command requesting the creation of a remote repository.

```text
Let's get you set up with a new repository. I'm going to create a folder called

    article

in the current working directory. If you haven't done this yet, please visit

    https://github.com/new

at this time and create an empty repository called

    rodluger/article
```

--------------------------------

### Install showyourwork

Source: https://show-your.work/en/latest/_sources/install.rst

Installs the package from PyPI or the development repository.

```bash
pip install showyourwork
```

```bash
pip install git+https://github.com/showyourwork/showyourwork
```

--------------------------------

### Install showyourwork with documentation dependencies

Source: https://show-your.work/en/latest/contributorguide

Installs the package in editable mode with documentation extras.

```bash
python -m pip install -e ".[docs]"
```

--------------------------------

### Serve documentation locally

Source: https://show-your.work/en/latest/contributorguide

Starts a local web server to view the generated documentation files.

```bash
python3 -m http.server -d _build/html
```

--------------------------------

### Setup a test project

Source: https://show-your.work/en/latest/contributorguide

Initializes a new project directory using the specific branch version of showyourwork.

```bash
showyourwork setup -a git+https://github.com/showyourwork/showyourwork@branch-name foo/bar
```

--------------------------------

### Setup Overleaf Integration

Source: https://show-your.work/en/latest/_sources/cli.rst

Command to initialize showyourwork with a specific Overleaf project ID.

```bash
showyourwork setup --overleaf=62150dd16134ef045f81d1c8
```

--------------------------------

### Build process output

Source: https://show-your.work/en/latest/_sources/quickstart.rst

Example of the console output displayed during the article build process.

```html
<pre>
    <span style="color:green;">Setting up the workflow...</span>
    <span style="color:green;">Generating the article PDF...</span>
    <span style="color:green;">Done!</span>
    </pre>
```

--------------------------------

### Initialize Overleaf Integration

Source: https://show-your.work/en/latest/_sources/overleaf.rst

Run the setup command locally to link the repository with the specified Overleaf project ID.

```bash
showyourwork setup rodluger/article --overleaf=6272c02ffe09ce2c9a5f0ff6
```

--------------------------------

### Initialize a new article repository

Source: https://show-your.work/en/latest/_sources/cli.rst

Use the setup command to create a new repository structure in the current directory. Replace $USER and $REPO with your GitHub credentials.

```bash
showyourwork setup $USER/$REPO
```

--------------------------------

### Configuring Overleaf Integration

Source: https://show-your.work/en/latest/_sources/overleaf.rst

Example configuration for the showyourwork.yml file to enable synchronization with an Overleaf project.

```yaml
overleaf:
    id: <ID>
    push:
        - src/tex/figures
        - src/tex/output
    pull:
        - src/tex/ms.tex
        - src/tex/bib.bib
```

--------------------------------

### Install in editable mode

Source: https://show-your.work/en/latest/contributorguide

Installs the package in editable mode to allow for easy branch switching without reinstallation.

```bash
pip install -e .
```

--------------------------------

### Install datrie via conda

Source: https://show-your.work/en/latest/_sources/faqs.rst

Use this command to install the datrie dependency if pip installation fails due to missing C/C++ compilers.

```bash
conda install -c conda-forge datrie
```

--------------------------------

### Install TinyTex for matplotlib LaTeX rendering

Source: https://show-your.work/en/latest/_sources/faqs.rst

Add this step to GitHub Actions workflows to install a lightweight TeX distribution for matplotlib.

```yaml
- name: Install TinyTex for matplotlib LaTeX rendering
  id: tinytex
  shell: bash -l {0}
  run: |
    wget -qO- "https://yihui.org/tinytex/install-bin-unix.sh" | sh
    sudo ~/bin/tlmgr install type1cm cm-super
```

--------------------------------

### Check git version

Source: https://show-your.work/en/latest/faqs

Verify the installed version of git to ensure compatibility with showyourwork! requirements.

```bash
git --version
```

--------------------------------

### Reproducibility paragraph template

Source: https://show-your.work/en/latest/latex

Example LaTeX text for an appendix explaining the reproducibility workflow and Zenodo integration.

```latex
This study was carried out using the reproducibility software
\href{https://github.com/showyourwork/showyourwork}{\showyourwork}
\citep{Luger2021}, which leverages continuous integration to
programmatically download the data from
\href{https://zenodo.org/}{zenodo.org}, create the figures, and
compile the manuscript. Each figure caption contains two links: one
to the dataset stored on zenodo used in the corresponding figure,
and the other to the script used to make the figure (at the commit
corresponding to the current build of the manuscript). The git
repository associated to this study is publicly available at
\url{https://github.com/mathren/CE_accretors}, and the release
v.2.1 allows anyone to re-build the entire manuscript. The datasets
are stored at \url{https://doi.org/10.5281/zenodo.7343715}, including
the template setup to recreate them using MESA (version 15140 and
the software development kit \texttt{x86\_64-linux-20.12.1}) and
the scripts used to produce the figures.
```

--------------------------------

### Identify missing class file errors

Source: https://show-your.work/en/latest/_sources/faqs.rst

Example of a build failure log indicating a missing LaTeX class file.

```text
Failed to compile manuscript. Perhaps you forgot to `\usepackage{showyourwork}`?
For more information, check out the log file:
.showyourwork/logs/tectonic.log
```

```text
**
(ms.tex
LaTeX2e <2020-02-02> patch level 5
L3 programming layer <2020-03-06>

! LaTeX Error: File `aastex631.cls' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: cls)

Enter file name:
```

--------------------------------

### HTML Directory Structure

Source: https://show-your.work/en/latest/_sources/overleaf.rst

Example HTML structure for displaying a file system directory using the directory-list class.

```html
<div class="box">
        <ul class="directory-list">
          <li class="folder">figures
            <ul>
                <li>.gitignore</li>
            </ul>
          </li>
          <li class="folder">output
            <ul>
                <li>.gitignore</li>
            </ul>
          </li>
          <li>.gitignore</li>
          <li>bib.bib</li>
          <li>ms.tex</li>
          <li>showyourwork.sty</li>
        </ul>
      </div>
```

--------------------------------

### Override Build Cores

Source: https://show-your.work/en/latest/_sources/cli.rst

Example of overriding the default core count for the build process.

```bash
showyourwork build -c2
```

--------------------------------

### Test a pull request

Source: https://show-your.work/en/latest/_sources/contributorguide.rst

Commands to clone, fetch, and install a pull request branch for testing purposes.

```bash
git clone https://github.com/showyourwork/showyourwork.git
```

```bash
git fetch
```

```bash
git switch branch-name
```

```bash
pip install -e .
```

```bash
showyourwork setup -a git+https://github.com/showyourwork/showyourwork@branch-name foo/bar
```

```bash
showyourwork build
```

--------------------------------

### Define a custom preprocess_arxiv_script

Source: https://show-your.work/en/latest/_sources/config.rst

A bash script example to modify manuscript files for arXiv compatibility, such as adjusting minted cache settings and xcolor options.

```bash
#!/bin/bash
pushd $1
sed -i ms.tex -e 's/finalizecache/frozencache/g'
sed -i ms.tex -e '/PassOptionsToPackage/d'
sed -i showyourwork.tex -e 's/RequirePackage{xcolor}/RequirePackage[table]{xcolor}/g'
popd
```

--------------------------------

### Conda UnsatisfiableError Example

Source: https://show-your.work/en/latest/_sources/faqs.rst

A sample output showing the error message generated when conda fails to resolve package dependencies.

```text
Collecting package metadata (repodata.json): done
Solving environment: \
Found conflicts! Looking for incompatible packages.
This can take several minutes.  Press CTRL-C to abort.
failed                                                                                                                                                                          \
Solving environment: \
Found conflicts! Looking for incompatible packages.
This can take several minutes.  Press CTRL-C to abort.
failed

UnsatisfiableError: The following specifications were found to be incompatible with each other:

Output in format: Requested package -> Available versions

Package python conflicts for:

...

Note that strict channel priority may have removed packages required for satisfiability.
```

--------------------------------

### Specify Zenodo Dataset DOI

Source: https://show-your.work/en/latest/_sources/config.rst

Example of mapping a specific Zenodo version DOI to a local file path.

```yaml
datasets:
  10.5281/zenodo.6468327:
    contents:
      TOI640b.json: src/data/TOI640b.json
```

--------------------------------

### View LaTeX compilation error message

Source: https://show-your.work/en/latest/faqs

Example of a generic compilation error message displayed when a manuscript fails to build.

```text
Failed to compile manuscript. Perhaps you forgot to `\usepackage{showyourwork}`?
For more information, check out the log file:
.showyourwork/logs/tectonic.log

```

--------------------------------

### Build and serve documentation combined

Source: https://show-your.work/en/latest/contributorguide

Executes the build and server commands sequentially for rapid development.

```bash
make html && python3 -m http.server -d _build/html
```

--------------------------------

### TeX figure inclusion

Source: https://show-your.work/en/latest/_sources/zenodo.rst

Example of how to include the generated figure in a LaTeX document.

```TeX
...

\begin{figure}[ht!]
    \script{figure.py}
    \begin{centering}
        \includegraphics{figures/figure.pdf}
        \caption{Simulation results.}
        \label{fig:figure}
    \end{centering}
\end{figure}

...
```

--------------------------------

### Build and serve documentation

Source: https://show-your.work/en/latest/_sources/contributorguide.rst

Commands to build the documentation locally and serve it via a web server.

```text
conda activate sywdocs
```

```text
cd docs
```

```text
make html
```

```text
python3 -m http.server -d _build/html
```

```text
make html && python3 -m http.server -d _build/html
```

--------------------------------

### Set up documentation environment

Source: https://show-your.work/en/latest/_sources/contributorguide.rst

Commands to create and activate a conda environment for building documentation.

```bash
conda create -n sywdocs python pip
```

```bash
conda activate sywdocs
```

```bash
python -m pip install -e ".[docs]"
```

--------------------------------

### Display build help

Source: https://show-your.work/en/latest/cli

View the usage instructions and available options for the build command.

```bash
showyourwork build --help
```

--------------------------------

### Create a Zenodo Sandbox cache

Source: https://show-your.work/en/latest/_sources/zenodo.rst

Run this command to initialize a new Zenodo Sandbox deposit for the current branch.

```bash
showyourwork cache create
```

--------------------------------

### Build documentation HTML

Source: https://show-your.work/en/latest/contributorguide

Compiles reStructured Text files into HTML format using make.

```bash
make html
```

--------------------------------

### Initialize a new repository

Source: https://show-your.work/en/latest/_sources/quickstart.rst

Creates a new article repository folder in the current directory using the specified GitHub slug.

```bash
showyourwork setup rodluger/article
```

--------------------------------

### Handling ignored files

Source: https://show-your.work/en/latest/quickstart

Example of the error message encountered when attempting to add a file tracked by .gitignore.

```bash
git add src/tex/figures/random_numbers.pdf

The following paths are ignored by one of your .gitignore files:
src/tex/figures/random_numbers.pdf
Use -f if you really want to add them.
```

--------------------------------

### Clone and build an article repository

Source: https://show-your.work/en/latest/_sources/quickstart.rst

Commands to download an existing article repository and initiate the build process locally.

```bash
git clone https://github.com/user/repo
cd repo
```

```bash
showyourwork
```

--------------------------------

### Activate documentation environment

Source: https://show-your.work/en/latest/contributorguide

Activates the previously created sywdocs environment.

```bash
conda activate sywdocs
```

--------------------------------

### Expensive figure script example

Source: https://show-your.work/en/latest/_sources/zenodo.rst

A monolithic script that performs both simulation and plotting, causing re-runs on any change.

```python
import simulation
import matplotlib.pyplot as plt
import paths

# Run the simulation for some inputs
simulation.run(x=10, y=25)
data = simulation.get_results()

# Plot the results
fig, ax = plt.subplots(1)
ax.plot(data, color="k")
fig.savefig(paths.figures / "figure.pdf")
```

--------------------------------

### Display showyourwork clean help

Source: https://show-your.work/en/latest/cli

View the usage instructions and available options for the clean command.

```bash
showyourwork clean --help
```

--------------------------------

### Execute Article Build Action

Source: https://show-your.work/en/latest/_sources/layout.rst

Invokes the showyourwork-action to generate the article PDF.

```yaml
- name: Build the article PDF
  id: build
  uses: showyourwork/showyourwork-action@v1
```

--------------------------------

### Build an article

Source: https://show-your.work/en/latest

Execute the build command to generate the article PDF.

```bash
showyourwork build
```

--------------------------------

### Disable LaTeX rendering in matplotlib

Source: https://show-your.work/en/latest/_sources/faqs.rst

Use this to bypass LaTeX installation requirements if full LaTeX rendering is not strictly necessary.

```python
import matplotlib.pyplot as plt
plt.rcParams.update({"text.usetex": False})
```

--------------------------------

### Build the article locally

Source: https://show-your.work/en/latest/_sources/quickstart.rst

Compiles the article PDF from the repository source files.

```bash
showyourwork build
```

```bash
showyourwork
```

--------------------------------

### Execute showyourwork build

Source: https://show-your.work/en/latest/quickstart

Run this command at the top level of the repository to initiate the automated build process.

```bash
showyourwork
```

--------------------------------

### Navigate to documentation directory

Source: https://show-your.work/en/latest/contributorguide

Changes the current working directory to the docs folder.

```bash
cd docs
```

--------------------------------

### Clone the repository

Source: https://show-your.work/en/latest/contributorguide

Initial step to obtain the source code from the official repository.

```bash
git clone https://github.com/showyourwork/showyourwork.git
```

--------------------------------

### Configure Computer Modern fonts in matplotlib

Source: https://show-your.work/en/latest/_sources/faqs.rst

Apply these settings in matplotlibrc to match manuscript fonts without requiring a full LaTeX installation.

```python
# set font to match LaTeX's Computer Modern
font.family: serif
font.serif: cmr10
mathtext.fontset: cm
axes.formatter.use_mathtext: True # needed when using cm=cmr10 for normal text
```

--------------------------------

### Explicitly import snakemake for type checking

Source: https://show-your.work/en/latest/_sources/snakefile.rst

Methods to resolve undefined snakemake object warnings in IDEs or linters based on the installed version.

```python
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from snakemake.iocontainers import snakemake
```

```python
from snakemake.script import snakemake
```

--------------------------------

### Display help information for showyourwork

Source: https://show-your.work/en/latest/cli

View the available commands and options for the showyourwork utility.

```bash
showyourwork --help
```

```text
Usage: showyourwork [OPTIONS] COMMAND [ARGS]...

  Easily build open-source, reproducible scientific articles.

Options:
  -v, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  build    Build an article in the current working directory.
  cache    Caching-related operations.
  clean    Clean the article build in the current working directory.
  setup    Set up a new article repository in the current working directory.
  tarball  Generate a tarball of the build in the current working directory.
```

--------------------------------

### GitHub Actions permission error output

Source: https://show-your.work/en/latest/_sources/faqs.rst

Example of the error message encountered when GitHub Actions lacks sufficient permissions to push to a repository fork.

```text
Uploading output
/tmp/tmp.KORuhtnUA7
Switched to a new branch 'main-pdf'
[main-pdf (root-commit) 224ecfd] force-push article output
2 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 arxiv.tar.gz
create mode 100644
remote: Permission to $USER/$REPO.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/$USER/$REPO/': The requested URL returned error: 403
```

--------------------------------

### Clone an article repository

Source: https://show-your.work/en/latest

Use git to clone the desired project repository and navigate into the directory.

```bash
git clone https://github.com/user/repo
cd repo
```

--------------------------------

### Create and activate a conda environment

Source: https://show-your.work/en/latest/_sources/install.rst

Sets up a dedicated environment with pip using mamba.

```bash
mamba create -n showyourwork pip
mamba activate showyourwork
```

--------------------------------

### Enable SyncTeX

Source: https://show-your.work/en/latest/_sources/config.rst

Toggle the generation of SyncTeX files for editor synchronization.

```yaml
synctex: true
```

--------------------------------

### Define pip dependencies

Source: https://show-your.work/en/latest/_sources/layout.rst

Pin exact versions for pip-installed packages in the environment.yml file.

```text
- pip:
  - matplotlib==3.3.4
```

--------------------------------

### Enable DAG Rendering

Source: https://show-your.work/en/latest/config

Basic configuration to enable the generation of the article dependency graph.

```yaml
dag:
  render: true
```

--------------------------------

### showyourwork cache create

Source: https://show-your.work/en/latest/cli

Creates a Zenodo Sandbox deposit draft for the specified branch.

```APIDOC
## showyourwork cache create

### Description
Creates a Zenodo Sandbox deposit draft for the given branch. Requires a Zenodo Sandbox API token provided as the environment variable and Github repository secret `SANDBOX_TOKEN`.

### Options
- **-b, --branch** (TEXT) - Optional - Branch whose deposit is to be deleted. Default is current branch.
```

--------------------------------

### Create a custom integration test

Source: https://show-your.work/en/latest/_sources/integration_tests.rst

Subclass TemporaryShowyourworkRepository and override the customize method to prepare the repository environment for testing.

```python
from helpers import TemporaryShowyourworkRepository
from showyourwork.config import edit_yaml

# A script that computes the age of the universe
variable_script = r"""
import paths
import numpy as np

# Compute the age of the universe
np.random.seed(42)
age = np.random.normal(14.0, 1.0)

# Write it to disk
with open(paths.output / "age_of_universe.txt", "w") as f:
    f.write(f"{age:.3f}")
"""

class TestLatexVariable(TemporaryShowyourworkRepository):
    """Test a workflow with dynamic quantities imported into the tex file."""

    def customize(self):
        """Create and edit all the necessary files for the workflow."""
        # Create the script
        with open(
            self.cwd / "src" / "scripts" / "age_of_universe.py", "w"
        ) as f:
            print(variable_script, file=f)

        # Import the variable into the tex file
        ms = self.cwd / "src" / "tex" / "ms.tex"
        with open(ms, "r") as f:
            ms_orig = f.read()
        with open(ms, "w") as f:
            ms_new = ms_orig.replace(
                r"\end{document}",
                r"Based on a detailed analysis of Planck observations of the cosmic "
                r"microwave background, we have determined the age of the universe "
                r"to be \variable{output/age_of_universe.txt} Gyr."
                "\n"
                r"\end{document}",
            )
            print(ms_new, file=f)

        # Add a Snakemake rule to run the script
        with open(self.cwd / "Snakefile", "r") as f:
            contents = f.read()
        with open(self.cwd / "Snakefile", "w") as f:
            print(contents, file=f)
            print("\n", file=f)
            print(
                "\n".join(
                    [
                        "rule age_of_universe:",
                        "    output:",
                        "        'src/tex/output/age_of_universe.txt'",
                        "    script:",
                        "        'src/scripts/age_of_universe.py'",
                    ]
                ),
                file=f,
            )
```

--------------------------------

### Manage Zenodo cache

Source: https://show-your.work/en/latest/cli

Displays help information for caching operations, including creating, deleting, and publishing deposits.

```bash
showyourwork cache --help
```

```text
Usage: showyourwork cache [OPTIONS] COMMAND [ARGS]...

  Caching-related operations.

Options:
  -h, --help  Show this message and exit.

Commands:
  create   Create a Zenodo Sandbox deposit draft for the given branch.
  delete   Delete the latest draft of a Zenodo Sandbox deposit.
  freeze   Publishes the current Zenodo Sandbox deposit draft for the...
  publish  Publishes the current Zenodo Sandbox deposit draft for the...
  reserve  Reserves a permanent, static DOI on Zenodo that can later be...
```

--------------------------------

### Create conda environment for documentation

Source: https://show-your.work/en/latest/contributorguide

Initializes a new conda environment named sywdocs with python and pip.

```bash
conda create -n sywdocs python pip
```

--------------------------------

### Freeze the Zenodo cache

Source: https://show-your.work/en/latest/_sources/zenodo.rst

Publish the current Zenodo Sandbox draft to a permanent deposit.

```bash
showyourwork cache freeze
```

--------------------------------

### Handle IncompleteFilesException

Source: https://show-your.work/en/latest/_sources/faqs.rst

Instructions displayed by showyourwork when Snakemake marks output files as incomplete.

```text
If you are sure that certain files are not incomplete, mark them as complete with

  showyourwork --cleanup-metadata <filenames>

To re-generate the files rerun your command with the --rerun-incomplete flag.
```

--------------------------------

### Configure Overleaf Push Files

Source: https://show-your.work/en/latest/_sources/config.rst

Lists files to be pushed to Overleaf after every build.

```yaml
overleaf:
    push:
        - src/tex/figures
```

--------------------------------

### Configure LaTeX Workshop for showyourwork

Source: https://show-your.work/en/latest/_sources/faqs.rst

Settings to integrate showyourwork with the VSCode LaTeX Workshop extension.

```json
{
  "latex-workshop.latex.external.build.command": "showyourwork",
  "latex-workshop.latex.external.build.args": ["build"],
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.latex.outDir": "%WORKSPACE_FOLDER%"
}
```

--------------------------------

### Configure script execution

Source: https://show-your.work/en/latest/_sources/config.rst

Define how different file extensions are executed to generate output files.

```yaml
scripts:
  py:
    python {script}
```

```yaml
scripts:
  ipynb:
    jupyter execute {script}
```

--------------------------------

### Build with mamba frontend

Source: https://show-your.work/en/latest/_sources/quickstart.rst

Uses the mamba executable for faster conda environment creation, available in showyourwork v0.4.2 and later.

```bash
showyourwork build --conda-frontend=mamba
```

--------------------------------

### Define static datasets

Source: https://show-your.work/en/latest/_sources/config.rst

Map Zenodo deposit DOIs to local file paths for static datasets.

```yaml
datasets:
  10.5281/zenodo.6468327:
    contents:
      TOI640b.json: src/data/TOI640b.json
  10.5281/zenodo.5794178:
    contents:
      KeplerRot-LAMOST.csv: src/data/KeplerRot-LAMOST.csv
```

--------------------------------

### showyourwork build

Source: https://show-your.work/en/latest/_sources/cli.rst

Builds the article PDF by executing a two-step Snakemake workflow to resolve dependencies and compile the manuscript.

```APIDOC
## showyourwork build

### Description
Executes the build process for the article. It parses the config, builds dependencies, and generates the final PDF.

### Parameters
- **--force** (flag) - Optional - Forces the build of specific files.
```

--------------------------------

### Publishing the cache to Zenodo

Source: https://show-your.work/en/latest/_sources/zenodo.rst

Migrates cached outputs from Zenodo Sandbox to Zenodo to generate a permanent DOI. Requires the ZENODO_TOKEN environment variable to be set.

```bash
showyourwork cache publish
```

--------------------------------

### zenodo_create(branch)

Source: https://show-your.work/en/latest/api/showyourwork.cli.commands.zenodo

Creates a new Zenodo Sandbox deposit draft for the specified branch.

```APIDOC
## zenodo_create(branch)

### Description
Create a new Zenodo Sandbox deposit. This command creates a new draft on Zenodo Sandbox.

### Parameters
- **branch** (str) - Required - Branch to create the cache for.
```

--------------------------------

### showyourwork cache freeze

Source: https://show-your.work/en/latest/cli

Publishes the current Zenodo Sandbox deposit draft for the given branch to Zenodo Sandbox.

```APIDOC
## showyourwork cache freeze

### Description
Publishes the current Zenodo Sandbox deposit draft for the given branch to Zenodo Sandbox. Useful for preserving the current cache state. Requires a Zenodo Sandbox API token provided as the environment variable and Github repository secret `SANDBOX_TOKEN`.

### Options
- **-b, --branch** (TEXT) - Optional - Branch whose deposit is to be deleted. Default is current branch.
```

--------------------------------

### Configure Overleaf Pull Files

Source: https://show-your.work/en/latest/_sources/config.rst

Lists files to be pulled from Overleaf before every build.

```yaml
overleaf:
    pull:
        - src/tex/ms.tex
        - src/tex/bib.bib
```

--------------------------------

### Overleaf Token Configuration Message

Source: https://show-your.work/en/latest/cli

Displays the instructions provided by the CLI when the --overleaf flag is used.

```text
You provided an Overleaf project id, so I'm going to set up Overleaf integration
for this repository. Please make sure at this time that you have defined the
OVERLEAF_TOKEN environment variable. In order for this to
work on GitHub Actions, please go to

    https://github.com/tmp/tmp/settings/secrets/actions/new

at this time and create OVERLEAF_TOKEN secret with your
Overleaf token.
```

--------------------------------

### GitHub Actions Workflow Configuration

Source: https://show-your.work/en/latest/_sources/action.rst

Defines a build job that checks out the repository and executes the showyourwork-action to generate a PDF.

```yaml
  jobs:
    build:
      runs-on: ubuntu-latest
      name: Build the article PDF
      concurrency: showyourwork-${{ github.ref }}
      steps:
        - name: Checkout
          uses: actions/checkout@v3
          with:
            fetch-depth: 0

        - name: Build the article PDF
          id: build
          uses: showyourwork/showyourwork-action@v1
          env:
            SANDBOX_TOKEN: ${{ secrets.SANDBOX_TOKEN }}
            OVERLEAF_TOKEN: ${{ secrets.OVERLEAF_TOKEN }}
```

--------------------------------

### Load Data and Save Figures with paths.py

Source: https://show-your.work/en/latest/_sources/layout.rst

Demonstrates using the paths module to resolve absolute paths for data loading and figure saving.

```python
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")
```

--------------------------------

### Advanced Zenodo File Mapping and Extraction

Source: https://show-your.work/en/latest/_sources/config.rst

Demonstrates mapping individual files, renaming files, and extracting nested contents from tarballs.

```yaml
datasets:
  10.5281/zenodo.6468327:
    destination: src/data/TOI640                 # default folder to extract files to
    contents:

      README.md:                                 # auto extracted to `src/data/TOI640/README.md`
      TOI640b.json: src/data/TOI640/planet.json  # rename the extracted file, just for fun

      images.tar.gz:                             # remote tarballs behave like folders w/ same name
        README.md:                               # auto extracted to `src/data/TOI640/images/README.md`
        S06:                                     # subfolder
          image.json: src/data/TOI640/S06.json   # rename and change destination folder
        S07:                                     # subfolder
          image.json: src/data/TOI640/S07.json   # rename and change destination folder

      lightcurves.tar.gz:                        # another tarball
        lightcurves:                             # files are nested inside `lightcurves` in this tarball
          README.md:                             # auto extracted to `src/data/TOI640/lightcurves/lightcurves/README.md`
          S06:                                   # subfolder
            lc.txt: src/data/TOI640/S06.txt      # rename and change destination folder
          S07:                                   # subfolder
            lc.txt: src/data/TOI640/S07.txt      # rename and change destination folder
```

--------------------------------

### Configure GitHub Actions Secrets

Source: https://show-your.work/en/latest/_sources/overleaf.rst

Navigate to the repository settings to add necessary credentials for GitHub Actions.

```text
https://github.com/rodluger/article/settings/secrets/actions/new
```
Tokens:
Raw