Exa-MA D7.1 Report Automation

GitHub Actions Status

License

Table of Contents

• Overview
• Quick Start
  • Prerequisites
  • Clone and Setup
• Compiling the Document
  • Method 1: Using latexmk (Recommended)
  • Method 2: Helper commands with article-cli
  • Method 3: Using VS Code
  • Method 4: Single Pass Compilation
  • Method 5: Using the CLI Helper
  • Overleaf Workflow for Non-GitHub Users
  • Troubleshooting Compilation Issues
• Bibliography Management with Zotero
  • Updating References
    • Option 1: Using article-cli (Recommended)
    • Option 2: Manual Download from Zotero
  • Setting Up Zotero API Access
  • Custom Citation Keys
• Automated Workflows
  • GitHub Actions Pipeline
  • Release Process
  • Development Workflow
• Project Structure
  • Key Files
• Contributing
  • How to Contribute
  • Best Practices
• CLI Reference
• Technical Notes
  • System Requirements
  • Self-Hosted Runners
  • Compilation Notes
• Additional Resources
• License

Overview

This repository contains the Exa-MA D7.1 deliverable document written in LaTeX with automated compilation workflows. The project uses LaTeX with the minted package for syntax highlighting and requires special compilation flags. Documents are automatically compiled using GitHub Actions with self-hosted TeXLive runners and can be compiled locally using various methods.

Key features: - Automated LaTeX compilation with GitHub Actions - VS Code integration with LaTeX Workshop - Zotero bibliography management - Release automation with version tagging - Comprehensive error handling and troubleshooting

Quick Start

Prerequisites

Before compiling, ensure you have: - LaTeX distribution (TeX Live recommended) - Python with Pygments library (for code syntax highlighting) - Git (for version control and hooks)

Installing Pygments

# On macOS with Homebrew
brew install pygments

# On Ubuntu/Debian
sudo apt-get install python3-pygments

# Using pip
pip install pygments

Clone and Setup

git clone https://github.com/numpex/exa-ma-d7.1
cd exa-ma-d7.1
article-cli setup # to be done only once after you clone the repo

Note	article-cli is the recommended tool to setup the repo, create releases and update bibtex references. The legacy a.cli script still exists but is deprecated.

Compiling the Document

See AGENTS.md for compilation guide and FAST-COMPILE.md for optimization strategies.

Method 1: Using latexmk (Recommended)

The recommended compilation method uses latexmk with shell escape enabled:

Full compilation with latexmk

latexmk --shell-escape -pdf -file-line-error -halt-on-error -interaction=nonstopmode exa-ma-d7.1.tex

Key flags explained: - --shell-escape: Required for minted package (syntax highlighting) - -pdf: Generate PDF output - -file-line-error: Show file names and line numbers for errors - -halt-on-error: Stop compilation on errors - -interaction=nonstopmode: Continue compilation without user input

Method 2: Helper commands with article-cli

For faster iteration during development, use article-cli to manage common tasks (clean, update bibliography). For compilation, prefer the latexmk recipe above or VS Code auto-build.

Common helper commands

# Setup hooks (run once after clone)
article-cli setup

# Update bibliography from Zotero
article-cli update-bibtex

# Clean build artifacts
article-cli clean

Method 3: Using VS Code

If you’re using VS Code with the LaTeX Workshop extension:

1. Open the project in VS Code

2. The document will auto-compile when you save any .tex file

3. Use Ctrl+Alt+B (or Cmd+Alt+B on macOS) to manually build

The VS Code configuration is pre-configured in .vscode/settings.json with: - Auto-build on save enabled - Proper latexmk recipe with shell escape - SyncTeX support for forward/backward search

Method 4: Single Pass Compilation

For quick testing (may require multiple runs for references):

Single pdflatex run

pdflatex --shell-escape exa-ma-d7.1.tex

Method 5: Using the CLI Helper

Clean build artifacts

article-cli clean

Overleaf Workflow for Non-GitHub Users

For colleagues who prefer Overleaf over GitHub:

We provide standalone compilation files that compile in ~10-15 seconds instead of 5-10 minutes for the full document.

See 📘 Complete Overleaf Guide for detailed instructions.

Quick Overleaf workflow

# Export WP1 for Overleaf (creates a ZIP file)
./sync-overleaf.sh export WP1

# After editing in Overleaf, import changes back
./sync-overleaf.sh import overleaf-export-WP1.zip WP1

# List all available standalone files
./sync-overleaf.sh list

Available standalone files: standalone-wp1.tex through standalone-wp6.tex

Key benefits:

• ⚡ Fast compilation in Overleaf (~10-15 seconds vs 5-10 minutes)

• 🎓 No GitHub knowledge required

• 🔄 Seamless bidirectional sync with repository

• 🤖 Full document still compiles in CI/CD for releases

• 📦 Automatic dependency management (graphics, styles, etc.)

Troubleshooting Compilation Issues

Common errors and solutions:

Shell escape not enabled

Error: Package minted Error: You must invoke LaTeX with the -shell-escape flag.

Solution: Always use --shell-escape flag in your compilation command.

Pygments not found

Error: Package minted Error: You must have 'pygmentize' installed.

Solution: Install Python and Pygments as shown in the Prerequisites section.

Missing bibliography

If references are not showing up, ensure you have the latest references.bib file (see Zotero section).

Bibliography Management with Zotero

The project uses Zotero for bibliography management with the ExaMA shared library.

Updating References

To update references.bib, you have several options:

Option 1: Using article-cli (Recommended)

export ZOTERO_API_KEY=your_api_key_here
article-cli update-bibtex

Option 2: Manual Download from Zotero

Download references.bib by exporting the exa-ma library from the Zotero GUI.

Setting Up Zotero API Access

1. Go to Zotero Security Settings

2. Navigate to Applications at the bottom

3. Click Create new private key

4. Select Read only group permissions

5. Click Save Key

6. Store the key securely and use it for ZOTERO_API_KEY

Zotero Applications Setup

Creating New API Key

Custom Citation Keys

Citation Key Setup in Zotero

To set custom citation keys, add the following to Zotero’s Extra field:

Citation Key: author_title_year_type

Example: Citation Key: saigre_coupled_2024_paper

Note	When setting custom keys, ensure uniqueness to avoid conflicts.

Automated Workflows

GitHub Actions Pipeline

The repository uses GitHub Actions for automated compilation and release management:

Triggers: - Push to any branch: Compiles document and creates artifacts - Push version tags (v*): Creates official releases with PDF

Workflow stages: 1. Environment Setup: Selects appropriate runner (self-hosted self-texlive or ubuntu-latest) 2. Bibliography Update: Automatically fetches latest references from Zotero (non-main branches) 3. LaTeX Compilation: Compiles document using latexmk with shell escape 4. Artifact Creation: Uploads PDF and source files 5. Release Management: Creates GitHub releases for tagged versions

Self-hosted Runners: The project uses UNISTRA’s self-texlive runners, pre-configured with: - Complete TeXLive installation - All required LaTeX packages - Optimized compilation environment

Release Process

To create a new release (preferred flow):

# 1) Ensure main is up to date
git checkout main
git pull --ff-only

# 2) Bump version and changelog in exa-ma-d7.1.tex
#    - Set \delivVersion{vX.Y.Z}
#    - Add new \istChange{DD/MM/YYYY}{vX.Y.Z}{Authors}{Summary}

# 3) Update pyproject.toml version to X.Y.Z

# 4) Commit changes
git add exa-ma-d7.1.tex pyproject.toml
git commit -m "chore(release): vX.Y.Z"

# 5) Create an annotated tag and push using article-cli
python3 -m article_cli create vX.Y.Z
git push origin vX.Y.Z

Development Workflow

1. Setup: article-cli setup (one-time after clone)

2. Edit: Modify .tex files as needed

3. Compile: Use VS Code auto-build or manual latexmk

4. Clean: article-cli clean to remove build artifacts

5. Commit: Git hooks automatically update version info

6. Release: Tag with ./a.cli create vX.Y.Z for releases

Project Structure

The repository is organized as follows:

Directory/File	Description
exa-ma-d7.1.tex	Main LaTeX document
chapters/	Individual chapters of the deliverable
sections/	Report sections and content
software/	Software-specific sections
graphics/	Images, figures, and visual content
references.bib	Bibliography file (managed via Zotero)
numpex.sty	Custom LaTeX style files
a.cli	Legacy helper script (deprecated; use article-cli)
hooks/	Git hooks for automation
.vscode/	VS Code configuration
.github/workflows/	GitHub Actions workflows

Key Files

LaTeX Files: - exa-ma-d7.1.tex: Main document entry point - defs.tex: Definitions and macros - *.sty: Custom style files (numpex.sty, istcover.sty, etc.)

Configuration: - .vscode/settings.json: VS Code LaTeX Workshop configuration - .github/workflows/latex.yml: Automated compilation workflow - gitHeadLocal.gin: Version information (auto-generated)

Contributing

How to Contribute

1. Clone and Setup:

   git clone https://github.com/numpex/exa-ma-d7.1
   cd exa-ma-d7.1
   article-cli setup

2. Make Changes: Edit LaTeX sources in relevant directories (chapters/, sections/)

3. Test Compilation: Ensure document compiles without errors:

   latexmk --shell-escape -pdf -interaction=nonstopmode exa-ma-d7.1.tex

4. Clean Up: Remove build artifacts before committing:

   article-cli clean

5. Submit: Create a pull request for review

Best Practices

• Always test compilation before submitting changes

• Use meaningful commit messages that describe the changes

• Update bibliography when adding new references

• Follow LaTeX conventions for formatting and structure

• Clean build artifacts before committing

CLI Reference

The a.cli script provides several useful commands:

# Setup git hooks (run once after clone)
./a.cli setup

# Clean build artifacts
./a.cli clean

# Create a new release
python3 -m article_cli create v1.0.0

# List recent releases
git tag --list 'v*'

# Update bibliography from Zotero
article-cli update-bibtex

# Get help
article-cli --help

Technical Notes

System Requirements

• LaTeX Distribution: TeX Live (full installation recommended)

• Python: Version 3.6+ with Pygments library

• Git: For version control and hooks

• VS Code (optional): With LaTeX Workshop extension for optimal experience

Self-Hosted Runners

The project uses UNISTRA’s specialized self-texlive runners with: - Pre-installed complete TeXLive distribution - All required LaTeX packages - Optimized compilation environment - Automatic fallback to ubuntu-latest if unavailable

Compilation Notes

• Shell escape is mandatory due to the minted package for code highlighting

• Multiple passes may be needed for complete reference resolution

• SyncTeX is enabled for VS Code forward/backward search

• Build artifacts are automatically cleaned in CI/CD pipeline

Additional Resources

• AGENTS.md: Comprehensive LaTeX compilation guide

• GitHub Actions: View build status

• Releases: Download latest PDF

• Zotero Library: ExaMA shared bibliography

• VS Code LaTeX Workshop: Extension documentation

License

This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

You are free to: - Share — copy and redistribute the material in any medium or format - Adapt — remix, transform, and build upon the material for any purpose, even commercially

Under the following terms: - Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made

This document is a deliverable of the Exa-MA project (ANR-22-EXNU-0002), funded by the French National Research Agency (ANR) as part of the NUMPEX program.

Citation: When referencing this work, please cite as:

Exa-MA Consortium. (2025). Benchmarking Analysis Report (D7.1).
DOI: 10.5281/zenodo.15188286

See the LICENSE file for complete terms.