# 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
```bash
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:
```bash
├-- 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.
```bash
cd my-project
papersync create
```
The Git repo now looks like this:
```bash
├-- 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:
```yaml
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:
```bash
# 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`.
```bash
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:
```bash
├-- 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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rferrali/papersync",
"name": "papersync",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "latex, git, sync",
"author": "Romain Ferrali",
"author_email": "Romain Ferrali <rferrali@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/05/b3/6b1ed85ce2a606f31b4e5523c6e3e7fa92a7c124bf4422649b820308ef68/papersync-0.1.0.tar.gz",
"platform": null,
"description": "# papersync\n\npapersync 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.\n\npapersync 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.\n\npapersync 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.\n\n## Installation\n\nInstall from pip\n\n```bash\npip install papersync\n```\n\n## Usage: a minimal example\n\nSay 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: \n\n```bash\n\u251c-- main.R # the statistical code\n\u251c-- assets # the folder that contains the tables and figures created by main.R\n| \u251c-- tables\n| | \u2514-- my-table.tex\n| \u2514-- figures\n| \u2514-- my-figure.pdf\n\u2514-- tex # the folder that contains all the writing\n \u251c-- presentation\n | \u2514-- main.tex\n \u2514-- paper\n \u2514-- main.tex\n```\n\nThe team is working on a paper and a presentation. The paper is hosted on Overleaf, while the presentation is on Dropbox. \n\nTo 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:\n\n- **Public configuration file**, `./papersync.yaml`: Specifies the path to the assets directory and the local paths of each LaTeX project within the repository.\n- **Private configuration file**, `.env`: Indicates the remote paths for each project. As usual with .env files, this file is unique to each contributor\u2019s environment and should not be committed to the repository.\n\n```bash\ncd my-project\npapersync create\n```\n\nThe Git repo now looks like this: \n```bash\n\u251c-- main.R # the statistical code\n\u251c-- assets # the folder that contains the tables and figures created by main.R\n| \u251c-- tables\n| | \u2514-- my-table.tex\n| \u2514-- figures\n| \u2514-- my-figure.pdf\n\u251c-- tex # the folder that contains all the writing\n| \u251c-- presentation\n| | \u2514-- main.tex\n| \u2514-- paper\n| \u2514-- main.tex\n\u251c-- papersync.yaml # the public configuration file\n\u2514-- .env # the private confifguration file\n```\n\nThe file `papersync.yaml` should be specified as follows: \n\n```yaml\nassets: \"./assets\"\nprojects: \n article: \"./tex/article\"\n presentation: \"./tex/presentation\"\n```\n\nThe 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: \n\n```bash\n# other variables stored in .env\nSOME_VARIABLE=SOME_VALUE\n# variables required byt papersync\nPAPERSYNC_ARTICLE=\"/Users/alice/Library/CloudStorage/Dropbox/Apps/Overleaf/cool-paper\"\nPAPERSYNC_PRESENTATION=\"/Users/alice/Library/CloudStorage/Dropbox/projects/cool-project/presentation\"\n```\n\nAfter 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`.\n\n```bash\ncd my-project\npapersync push\npapersync pull\n```\n\nOn 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: \n```bash\n\u251c-- main.R # the statistical code\n\u251c-- assets # the folder that contains the tables and figures created by main.R\n| \u251c-- tables\n| | \u2514-- my-table.tex\n| \u2514-- figures\n| \u2514-- my-figure.pdf\n\u251c-- tex # the folder that contains all the writing\n| \u251c-- presentation\n| | \u251c-- assets # a symlink pointing to the assets folder in the root\n| | \u2514-- main.tex\n| \u2514-- paper\n| \u251c-- assets # a symlink pointing to the assets folder in the root\n| \u2514-- main.tex\n\u251c-- papersync.yaml # the public configuration file\n\u2514-- .env # the private confifguration file\n```\n\n\n",
"bugtrack_url": null,
"license": "GPL3",
"summary": "A tool for syncing LaTeX projects with Git and external folders.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/rferrali/papersync"
},
"split_keywords": [
"latex",
" git",
" sync"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f32df6bbf07ce4166b221621455460500f1af1327923a938b0e38cc019970d9b",
"md5": "9c8d560f7f32e66b96a90950c917226a",
"sha256": "7e86e638404e8f92abe9c9e9fd4f2d9cdf4c218d2072e92fbcebdb1ea094f13c"
},
"downloads": -1,
"filename": "papersync-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c8d560f7f32e66b96a90950c917226a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19703,
"upload_time": "2024-11-24T22:33:41",
"upload_time_iso_8601": "2024-11-24T22:33:41.077788Z",
"url": "https://files.pythonhosted.org/packages/f3/2d/f6bbf07ce4166b221621455460500f1af1327923a938b0e38cc019970d9b/papersync-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "05b36b1ed85ce2a606f31b4e5523c6e3e7fa92a7c124bf4422649b820308ef68",
"md5": "adcab0ba5ad3b43f17eafa1fce0d6d43",
"sha256": "9af9faa5e1e76b2963ad824d2ef23e292adc60296b0f92b713d6a22bf38610b9"
},
"downloads": -1,
"filename": "papersync-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "adcab0ba5ad3b43f17eafa1fce0d6d43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19139,
"upload_time": "2024-11-24T22:33:43",
"upload_time_iso_8601": "2024-11-24T22:33:43.016906Z",
"url": "https://files.pythonhosted.org/packages/05/b3/6b1ed85ce2a606f31b4e5523c6e3e7fa92a7c124bf4422649b820308ef68/papersync-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 22:33:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rferrali",
"github_project": "papersync",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.1"
]
]
},
{
"name": "GitPython",
"specs": [
[
">=",
"3.1"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"5.3"
]
]
}
],
"lcname": "papersync"
}
JSON
