This repository contains the boilerplate elements for a computational paper built from Python notebook(s).
Such paper consists of
- code and data
- manuscript in the form of a computational Python notebook mixing code, computation results and narrative with a simple Markdown syntax
- possibly other support notebooks as supplementary materials
- a companion A0 poster
- Runfile to build the paper from scratch with simple commands (e.g.
run pdf
to build the journal-fromatted PDF, orrun poster
) - Configuration options
The deliverables consist of the paper and poster in PDF and HTML format. They are published automatically at this Gihub page for convenience. This is achived by a GitHub action which uploads the deliverables folder.
-
Directories organized similarly to Cookiecutter Data Science
-
Python best-practices: reusable code in a module in
src/
, unit tests intests/
and standalone notebooks. -
Proper git setup (git LFS, git ignore, ...)
-
Paper manuscript in Quarto markdown. Ability to mix code, illustrations and narrative story in a lean syntax. Support all elements of a formal paper. See "Technical Writing and Publishing Data-Rich Articles with Quarto"
-
Runfile automating all frequency commands (build, release, ...).
-
Commands to generate IEEE-formatted PDF, and HTML version for quick preview
-
Commands to generate a A0 poster (HTML and PDF) using the BetterPoster approach also from Quarto Markdown source.
-
Command to publish to Gdrive
-
Configures Gitlab to post the deliverables online in Gitlab pages.
-
tbump configuration for managing version tag.
-
Plain 1-column PDF format also available for supplementary notes
These instructions are valid for Linux OS.
Install the pre-requisites
- Conda or another python installation
- Quarto
- a Latex installation
- google-chrome. The poster PDF rendering relies on printing to PDF via google-chrome.
- UV
Install the Python dependencies in a Virtual environment (one-time only). Install also the current package under development in editable mode for convenience using sitepath
uv sync
python -m sitepath .
Activate the virtual environment either manually:
source .venv/bin/activate
export QUARTO_PYTHON=$(which python)
Or automatically by copying the above command in the file .in
and the autovenv plugin or equivalent.
At all times, you might verify that the environment is set up properly by consulting the following variables:
echo $VIRTUAL_ENV
echo $QUARTO_PYTHON
To build the paper HTML and the poster:
run html
run poster
To run in VScode, you have to set the interpreter correctly.
Edit the file .vsdode/settings.json' and adjust the variable
python.defaultInterpreterPath`.
Here are two articles generated from Quarto. The template here was derived from these.
-
G. Close, “Technical Writing and Publishing Data-Rich Articles with Quarto,” Sep. 22, 2022. [Online]. Available: https://gael-close.github.io/posts/2209-tech-writing/2209-tech-writing.html.
-
B. Brajon, E. Gasparin, and G. Close, “A benchmark of integrated magnetometers and magnetic gradiometers,” IEEE Access, vol. 11, pp. 115635–115643, 2023, https://doi.org/10.1109/ACCESS.2023.3325035.
The poster stylesheet is taken from https://github.com/hits-mbm-dev/paper-talin-loop/.