papersync 0.1.0

A tool for syncing LaTeX projects with Git and external folders.

papersync

papersync is designed to bridge the gap in academic projects where contributors have different roles: some focus on coding and producing tables and figures, while others focus solely on writing. In these cases, integrated solutions like Python notebooks are often unsuitable because (1) writers may not use statistical software, and (2) writing often requires precise formatting that advanced tools like LaTeX can provide, which simple Markdown-to-LaTeX conversions cannot match. Consequently, such projects often resort to cloud storage solutions without version control, missing the advantages of tracking changes in both code and LaTeX.

papersync addresses this need by enabling the synchronization of LaTeX projects managed in a Git repository with directories outside the repository (e.g., a Dropbox folder). The program ackage is built with the assumption that the Git repository maintains a central library of shared tables and figures (by default, ./assets), with each LaTeX project stored in its own folder within the repository (e.g., ./tex/article for the paper, and ./tex/presentation for the slides). papersync provides two commands,push and pull, to streamline syncing the local copy of each project with their remote counterpart.

papersync simplifies collaboration by allowing coders and writers to work seamlessly within their preferred tools while benefiting from the version control and change-tracking capabilities of Git. As a CLI program, it can be easily integrated with Makefiles or other automation scripts.

Installation

Install from pip

pip install papersync

Usage: a minimal example

Say that Alice, Bob, and Charles are all working on a project. Alice and Bob are the writers/coders, and Charles is only a writer. The Git repo is structured as follows:

├-- main.R # the statistical code
├-- assets # the folder that contains the tables and figures created by main.R
|   ├-- tables
|   |   └-- my-table.tex
|   └-- figures
|       └-- my-figure.pdf
└-- tex # the folder that contains all the writing
    ├-- presentation
    |   └-- main.tex
    └-- paper
        └-- main.tex

The team is working on a paper and a presentation. The paper is hosted on Overleaf, while the presentation is on Dropbox.

To get started, open a terminal, navigate to the repo, and type papersync create to set up papersync in a new or existing project. This will create/update two configuration files, and encourage you to modify them according to your needs:

• Public configuration file, ./papersync.yaml: Specifies the path to the assets directory and the local paths of each LaTeX project within the repository.
• Private configuration file, .env: Indicates the remote paths for each project. As usual with .env files, this file is unique to each contributor’s environment and should not be committed to the repository.

cd my-project
papersync create

The Git repo now looks like this:

├-- main.R # the statistical code
├-- assets # the folder that contains the tables and figures created by main.R
|   ├-- tables
|   |   └-- my-table.tex
|   └-- figures
|       └-- my-figure.pdf
├-- tex # the folder that contains all the writing
|   ├-- presentation
|   |   └-- main.tex
|   └-- paper
|       └-- main.tex
├-- papersync.yaml # the public configuration file
└-- .env # the private confifguration file

The file papersync.yaml should be specified as follows:

assets: "./assets"
projects: 
    article: "./tex/article"
    presentation: "./tex/presentation"

The file .env indicates where the project folders are stored in each of Alice's and Bob's computer. Indeed, the Dropbox location is different for each coauthor. As such, .env should not be committed to Git. You should add it to the .gitignore. Here is how .env looks for Alice:

# other variables stored in .env
SOME_VARIABLE=SOME_VALUE
# variables required byt papersync
PAPERSYNC_ARTICLE="/Users/alice/Library/CloudStorage/Dropbox/Apps/Overleaf/cool-paper"
PAPERSYNC_PRESENTATION="/Users/alice/Library/CloudStorage/Dropbox/projects/cool-project/presentation"

After initialization, both Alice and Bob can use papersync push from the CLI to push the latest version of each project to its corresponding remote directory, along with the assets folder. To synchronize the current state of each remote project directory back into the repository (e.g., after Charles has made some changes), they can use papersync pull.

cd my-project
papersync push
papersync pull

On pushing or pulling, papersync will create symlinks in each project directory, pointing to the assets library, so the projects can refer to the library using local file paths. This can also be done using the papersync link command. The final file structure will look like:

├-- main.R # the statistical code
├-- assets # the folder that contains the tables and figures created by main.R
|   ├-- tables
|   |   └-- my-table.tex
|   └-- figures
|       └-- my-figure.pdf
├-- tex # the folder that contains all the writing
|   ├-- presentation
|   |   ├-- assets # a symlink pointing to the assets folder in the root
|   |   └-- main.tex
|   └-- paper
|       ├-- assets # a symlink pointing to the assets folder in the root
|       └-- main.tex
├-- papersync.yaml # the public configuration file
└-- .env # the private confifguration file