From b07de546cf7825a32bafe592da42b262845df34f Mon Sep 17 00:00:00 2001 From: Christophe Prud'homme Date: Mon, 8 Dec 2025 07:02:14 +0100 Subject: [PATCH 1/7] feat: migrate from a.cli to article-cli - Add pyproject.toml with article-cli configuration - Update GitHub Actions workflow to use article-cli commands - Update README with article-cli documentation Closes #9 --- .github/workflows/latex.yml | 94 +++++++++++++++------- README.md | 154 ++++++++++++++++++++++++------------ pyproject.toml | 33 ++++++++ 3 files changed, 201 insertions(+), 80 deletions(-) create mode 100644 pyproject.toml diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index 0186571..b111ce3 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -44,8 +44,8 @@ jobs: echo "prefixwithref=$prefixwithref" >> "$GITHUB_OUTPUT" echo "pdf=$prefixwithref.pdf" >> "$GITHUB_OUTPUT" echo "tex=$prefix.tex" >> "$GITHUB_OUTPUT" - - - name: Show Outputs + + - name: Show Outputs run: | echo "runner=${{ steps.texlive_runner.outputs.runner }}" echo "prefix=${{ steps.doc_prefix.outputs.prefix }}" @@ -53,7 +53,6 @@ jobs: echo "pdf=${{ steps.doc_prefix.outputs.pdf }}" echo "tex=${{ steps.doc_prefix.outputs.tex }}" - build_latex: needs: workflow-setup runs-on: ${{ needs.workflow-setup.outputs.runner }} @@ -66,27 +65,50 @@ jobs: with: clean: true - - name: Install hooks + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install article-cli + run: | + pip install article-cli>=1.3.0 + + - name: Setup git hooks + run: | + article-cli setup + + - name: Install fonts run: | - bash ./a.cli setup + article-cli install-fonts - - name: Compile LaTeX document + - name: Compile LaTeX document (ubuntu-latest) uses: xu-cheng/latex-action@v3 if: ${{ needs.workflow-setup.outputs.runner == 'ubuntu-latest' }} with: root_file: ${{ needs.workflow-setup.outputs.tex }} latexmk_shell_escape: true + latexmk_use_xelatex: true post_compile: "latexmk -c; rm -rf _minted*" - - name: Compile LaTeX document + - name: Compile LaTeX document (self-hosted) if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} run: | - latexmk -shell-escape -xelatex -file-line-error -halt-on-error -interaction=nonstopmode ${{ needs.workflow-setup.outputs.tex }} + article-cli compile ${{ needs.workflow-setup.outputs.tex }} --engine xelatex --shell-escape - - name: Compile Poster + - name: Compile Poster (ubuntu-latest) + uses: xu-cheng/latex-action@v3 + if: ${{ needs.workflow-setup.outputs.runner == 'ubuntu-latest' }} + with: + root_file: poster.template.tex + latexmk_shell_escape: true + latexmk_use_xelatex: true + post_compile: "latexmk -c; rm -rf _minted*" + + - name: Compile Poster (self-hosted) if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} run: | - latexmk -shell-escape -xelatex -file-line-error -halt-on-error -interaction=nonstopmode poster.template.tex + article-cli compile poster.template.tex --engine xelatex --shell-escape - name: Rename PDF run: mv ${{ needs.workflow-setup.outputs.prefix }}.pdf ${{ needs.workflow-setup.outputs.pdf }} @@ -102,62 +124,74 @@ jobs: ./*.bbl ./${{ needs.workflow-setup.outputs.pdf }} ./poster.template.pdf - ./README.adoc + ./README.md ./hooks* ./img* ./fonts/* ./dat* ./*.png - ./a.cli ./*.sty ./exclude.txt ./sections* ./litterature* ./images* + ./pyproject.toml !./.git* !./.github* !./.vscode* !./.idea* !./.DS_Store* !./.gitignore* + check: - needs: [build_latex,workflow-setup] - runs-on: ${{ needs.workflow-setup.outputs.runner }} - name: Check LaTeX Artifact - steps: - - - name: Download Artifact + needs: [build_latex, workflow-setup] + runs-on: ${{ needs.workflow-setup.outputs.runner }} + name: Check LaTeX Artifact + steps: + - name: Download Artifact uses: actions/download-artifact@v4 with: name: ${{ needs.workflow-setup.outputs.prefixwithref }} path: ${{ github.workspace }}/artifact - - - name: List Artifact + + - name: List Artifact run: ls -R ${{ github.workspace }} - - - name: Check compilation of LaTeX document from artifact + + - name: Check compilation (ubuntu-latest) if: ${{ needs.workflow-setup.outputs.runner == 'ubuntu-latest' }} uses: xu-cheng/latex-action@v3 with: root_file: ${{ needs.workflow-setup.outputs.tex }} latexmk_shell_escape: true + latexmk_use_xelatex: true post_compile: "latexmk -c; rm -rf _minted*" working_directory: ${{ github.workspace }}/artifact - - - name: Check compilation of LaTeX document from artifact + + - name: Set up Python (self-hosted) + if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install article-cli (self-hosted) if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} run: | - latexmk -shell-escape -xelatex -file-line-error -halt-on-error -interaction=nonstopmode ${{ needs.workflow-setup.outputs.tex }} + pip install article-cli>=1.3.0 + + - name: Check compilation (self-hosted) + if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} + run: | + article-cli compile ${{ needs.workflow-setup.outputs.tex }} --engine xelatex --shell-escape working-directory: ${{ github.workspace }}/artifact - - - name: Check compilation of poster from artifact + + - name: Check poster compilation (self-hosted) if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} run: | - latexmk -shell-escape -xelatex -file-line-error -halt-on-error -interaction=nonstopmode poster.template.tex - working-directory: ${{ github.workspace }}/artifact + article-cli compile poster.template.tex --engine xelatex --shell-escape + working-directory: ${{ github.workspace }}/artifact release: - needs: [workflow-setup,build_latex, check] + needs: [workflow-setup, build_latex, check] runs-on: ${{ needs.workflow-setup.outputs.runner }} name: Create Release if: startsWith(github.ref, 'refs/tags/v') diff --git a/README.md b/README.md index 1637991..239ba11 100644 --- a/README.md +++ b/README.md @@ -2,91 +2,145 @@ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15113190.svg)](https://doi.org/10.5281/zenodo.15113190) [![GitHub Release](https://img.shields.io/github/v/release/numpex/presentation.template)](https://github.com/numpex/presentation.template/releases/latest) +[![PyPI - article-cli](https://img.shields.io/pypi/v/article-cli?label=article-cli)](https://pypi.org/project/article-cli/) [![Slack](https://img.shields.io/badge/slack-presentation-brightgreen.svg?logo=slack)](https://numpex.slack.com/archives/C08L4KHUTFX) [![Slack](https://img.shields.io/badge/slack-notifications-blue.svg?logo=slack)](https://numpex.slack.com/archives/C08KRJF3B55) ## Getting Started -Just clone the repository, add the path to your `TEXINPUTS` environment variable, and you are ready to use the theme in your presentation by adding: +This template uses [article-cli](https://pypi.org/project/article-cli/) for project management. + +### Installation + +```bash +pip install article-cli +``` + +### Quick Start + +Clone the repository and add the path to your `TEXINPUTS` environment variable, then use the theme in your presentation: ```latex \usetheme{numpex} ``` -### Slides template +### Slides Template -Checkout `presentation.template.tex`: +Compile `presentation.template.tex`: -```shell -bash a.cli build presentation.template.tex +```bash +article-cli compile --engine xelatex presentation.template.tex ``` -### Poster template +### Poster Template -Checkout `poster.template.tex`: +Compile `poster.template.tex`: -```shell -bash a.cli build poster.template.tex +```bash +article-cli compile --engine xelatex poster.template.tex ``` ## Fonts -For a better result, you should install the [Marianne font](https://www.systeme-de-design.gouv.fr/elements-d-interface/fondamentaux-de-l-identite-de-l-etat/typographie/) and compile with XeTeX. +For the best result, you should install the [Marianne font](https://www.systeme-de-design.gouv.fr/elements-d-interface/fondamentaux-de-l-identite-de-l-etat/typographie/) and compile with XeLaTeX. + +### Installing Fonts + +Install the required fonts (Marianne and Roboto) using article-cli: + +```bash +article-cli install-fonts +``` + +This downloads and extracts the fonts into the `fonts/` directory within your project. The `beamerfontthemenumpex` package is already configured to use fonts from this relative path. -### Installing Marianne Fonts +### Manual Font Configuration -1. **Download the Fonts:** - - You can download the Marianne fonts using the provided `a.cli` script. Run the following command: - ```bash - bash a.cli installfonts - ``` - - This will download and extract the Marianne fonts into the `fonts/` directory within your project. +If you prefer manual installation, ensure your LaTeX configuration points to the `fonts/` directory. -2. **Configure LaTeX:** - - Ensure your LaTeX configuration points to the `fonts/` directory. The provided `beamerfontthemenumpex` package is already configured to use the relative path `fonts/`. +## Using This Theme in Other Projects + +You can install this theme in any LaTeX project using article-cli: + +```bash +# Install the numpex theme (default) +article-cli install-theme numpex + +# Or install from a custom URL +article-cli install-theme --url https://github.com/numpex/presentation.template.d/archive/refs/heads/main.zip + +# List available themes +article-cli install-theme --list +``` ## CI/CD Pipeline -This repository includes a GitHub Actions workflow to compile the LaTeX document and release the PDF artifact. The workflow is triggered on pushes to branches and tags. +This repository includes a GitHub Actions workflow that uses article-cli to compile LaTeX documents and create releases. The workflow is triggered on pushes to branches and tags. ### Workflow Steps -1. **Workflow Setup:** - - Determines the appropriate runner (`ubuntu-latest` or `self-texlive`) based on the availability of a self-hosted runner with the `self-texlive` label. +1. **Setup:** Installs Python and article-cli +2. **Install Fonts:** Downloads required fonts using `article-cli install-fonts` +3. **Build LaTeX:** Compiles documents using XeLaTeX via `article-cli compile` +4. **Release:** Creates GitHub releases for tagged commits (e.g., `v1.0.0`) -2. **Build LaTeX:** - - Compiles the LaTeX document using `latexmk` and `xelatex`. - - Renames the generated PDF to include the branch or tag name. +## Usage + +### Setup Project -3. **Check:** - - Downloads the artifact and verifies that the LaTeX document compiles correctly from the artifact. +```bash +article-cli setup +``` -4. **Release:** - - Creates a GitHub release for tagged commits (e.g., `v1.0.0`). - - Uploads the PDF and other relevant files as release assets. +### Compile Documents -## Usage +```bash +# Compile with XeLaTeX (required for custom fonts) +article-cli compile --engine xelatex presentation.template.tex + +# Compile all .tex files in the project +article-cli compile --engine xelatex +``` + +### Create a Release + +```bash +article-cli create v1.0.0 +``` + +### List Releases + +```bash +article-cli list +``` + +### Clean Build Artifacts + +```bash +article-cli clean +``` + +## Configuration + +Project settings are managed in `pyproject.toml`: + +```toml +[tool.article-cli] +[project] +type = "presentation" + +[latex] +engine = "xelatex" + +[fonts] +enabled = true +install_dir = "fonts" +``` + +## Legacy Script -- **Setup Hooks:** - ```bash - bash a.cli setup - ``` - -- **Create a Release:** - ```bash - bash a.cli create v1.0.0 - ``` - -- **List Releases:** - ```bash - bash a.cli list - ``` - -- **Compile the Document:** - ```bash - bash a.cli build your_document.tex - ``` +The old `a.cli` bash script is still available for backward compatibility but is deprecated. Please migrate to article-cli for new projects. ## Contributing diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..52c572c --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,33 @@ +[project] +name = "presentation-template" +version = "1.0.0" +description = "NumPEx Beamer presentation template" + +[tool.article-cli] +# Project configuration +[tool.article-cli.project] +type = "presentation" + +[tool.article-cli.presentation] +theme = "numpex" +aspect_ratio = "169" + +[tool.article-cli.documents] +main = "presentation.template.tex" +additional = ["poster.template.tex"] + +[tool.article-cli.latex] +engine = "xelatex" +shell_escape = true +build_dir = "build" + +[tool.article-cli.workflow] +output_dir = "build" +fonts_dir = "fonts" +install_fonts = true + +[tool.article-cli.git] +default_branch = "main" + +[tool.article-cli.fonts] +directory = "fonts" From 993a115c120f17e7c09eaef7fb9062e63016e4ae Mon Sep 17 00:00:00 2001 From: Christophe Prud'homme Date: Mon, 8 Dec 2025 08:44:10 +0100 Subject: [PATCH 2/7] chore: require article-cli>=1.3.1 for font download fixes --- .github/workflows/latex.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index b111ce3..8e484c1 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -72,7 +72,7 @@ jobs: - name: Install article-cli run: | - pip install article-cli>=1.3.0 + pip install article-cli>=1.3.1 - name: Setup git hooks run: | From 2f82fd969745d27f6039d1666b0e62d2e29c8469 Mon Sep 17 00:00:00 2001 From: Christophe Prud'homme Date: Mon, 8 Dec 2025 08:47:54 +0100 Subject: [PATCH 3/7] fix: use --no-cache-dir to ensure latest article-cli is installed --- .github/workflows/latex.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index 8e484c1..152c6ed 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -72,7 +72,7 @@ jobs: - name: Install article-cli run: | - pip install article-cli>=1.3.1 + pip install --no-cache-dir article-cli>=1.3.1 - name: Setup git hooks run: | @@ -176,7 +176,7 @@ jobs: - name: Install article-cli (self-hosted) if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} run: | - pip install article-cli>=1.3.0 + pip install --no-cache-dir article-cli>=1.3.1 - name: Check compilation (self-hosted) if: ${{ needs.workflow-setup.outputs.runner == 'self-texlive' }} From 1a8f3c170e01d5faa30e7253eb7896fb7b6693cf Mon Sep 17 00:00:00 2001 From: Christophe Prud'homme Date: Mon, 8 Dec 2025 09:41:15 +0100 Subject: [PATCH 4/7] fix: explicitly specify font sources and clear fonts dir before install - Add explicit font sources in pyproject.toml using GitHub URLs - Clear fonts directory before install to avoid stale cached fonts - Require article-cli>=1.3.2 --- .github/workflows/latex.yml | 4 +++- pyproject.toml | 5 +++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index 152c6ed..cc46b7b 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -72,7 +72,7 @@ jobs: - name: Install article-cli run: | - pip install --no-cache-dir article-cli>=1.3.1 + pip install --no-cache-dir 'article-cli>=1.3.2' - name: Setup git hooks run: | @@ -80,6 +80,8 @@ jobs: - name: Install fonts run: | + # Clear any stale cached fonts from previous runs + rm -rf fonts article-cli install-fonts - name: Compile LaTeX document (ubuntu-latest) diff --git a/pyproject.toml b/pyproject.toml index 52c572c..a43e1ed 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,3 +31,8 @@ default_branch = "main" [tool.article-cli.fonts] directory = "fonts" +# Use GitHub releases for reliable font downloads +sources = [ + { name = "Roboto", url = "https://github.com/googlefonts/roboto/releases/download/v2.138/roboto-unhinted.zip", description = "Google's sans-serif font family" }, + { name = "Roboto Mono", url = "https://github.com/googlefonts/RobotoMono/archive/refs/heads/main.zip", description = "Google's monospace font, good for code" } +] From 3a15f3d8dc560e46a9814d4022109659d1033604 Mon Sep 17 00:00:00 2001 From: Christophe Prud'homme Date: Mon, 8 Dec 2025 10:37:56 +0100 Subject: [PATCH 5/7] fix: don't delete committed Marianne fonts before installing Roboto --- .github/workflows/latex.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index cc46b7b..f892f8e 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -80,8 +80,8 @@ jobs: - name: Install fonts run: | - # Clear any stale cached fonts from previous runs - rm -rf fonts + # Install Roboto fonts alongside the committed Marianne fonts + # Don't delete fonts/ - it contains Marianne fonts committed to the repo article-cli install-fonts - name: Compile LaTeX document (ubuntu-latest) From 117005537684664266cb2c4f95b697a7143f0f0d Mon Sep 17 00:00:00 2001 From: Christophe Prud'homme Date: Mon, 8 Dec 2025 10:43:46 +0100 Subject: [PATCH 6/7] feat: add PDF summary to GitHub Actions job summary --- .github/workflows/latex.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index f892f8e..568608e 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -145,6 +145,21 @@ jobs: !./.DS_Store* !./.gitignore* + - name: Add PDF to Job Summary + run: | + echo "## 📄 Compiled PDFs" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| Document | Pages | Size |" >> $GITHUB_STEP_SUMMARY + echo "|----------|-------|------|" >> $GITHUB_STEP_SUMMARY + pdf_pages=$(pdfinfo ${{ needs.workflow-setup.outputs.pdf }} 2>/dev/null | grep "Pages:" | awk '{print $2}' || echo "N/A") + pdf_size=$(ls -lh ${{ needs.workflow-setup.outputs.pdf }} | awk '{print $5}') + echo "| 🎯 Presentation | $pdf_pages | $pdf_size |" >> $GITHUB_STEP_SUMMARY + poster_pages=$(pdfinfo poster.template.pdf 2>/dev/null | grep "Pages:" | awk '{print $2}' || echo "N/A") + poster_size=$(ls -lh poster.template.pdf | awk '{print $5}') + echo "| 📋 Poster | $poster_pages | $poster_size |" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "📦 **Artifact**: \`${{ needs.workflow-setup.outputs.prefixwithref }}\`" >> $GITHUB_STEP_SUMMARY + check: needs: [build_latex, workflow-setup] runs-on: ${{ needs.workflow-setup.outputs.runner }} From c9ae34def36826f2b3020e0db4576d3305b1ce49 Mon Sep 17 00:00:00 2001 From: Christophe Prud'homme Date: Mon, 8 Dec 2025 10:46:55 +0100 Subject: [PATCH 7/7] feat: upload presentation and poster PDFs as separate artifacts --- .github/workflows/latex.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml index 568608e..ad2fb79 100644 --- a/.github/workflows/latex.yml +++ b/.github/workflows/latex.yml @@ -145,6 +145,18 @@ jobs: !./.DS_Store* !./.gitignore* + - name: Upload Presentation PDF + uses: actions/upload-artifact@v4 + with: + name: ${{ needs.workflow-setup.outputs.pdf }} + path: ${{ needs.workflow-setup.outputs.pdf }} + + - name: Upload Poster PDF + uses: actions/upload-artifact@v4 + with: + name: poster.template.pdf + path: poster.template.pdf + - name: Add PDF to Job Summary run: | echo "## 📄 Compiled PDFs" >> $GITHUB_STEP_SUMMARY