Metadata-Version: 2.1
Name: mendeley-watchdog
Version: 0.0.2
Summary: Continuously monitor a file and mirror the content after modification
Home-page: https://github.com/vlntnwbr/mendeley-watchdog
Author: Valentin Weber
Author-email: dev@vweber.eu
License: EUPL v1.2 or later
Project-URL: Bug Tracker, https://github.com/vlntnwbr/mendeley-watchdog/issues?q=label%3bug
Project-URL: Documentation, https://github.com/vlntnwbr/mendeley-watchdog/tree/v0.0.2/docs
Platform: UNKNOWN
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Requires-Python: >=3.8
Description-Content-Type: text/markdown

<!--- Copyright (c) 2021 Valentin Weber

    This file is part of the software mendeley-watchdog.

    The software is licensed under the European Union Public License
    (EUPL) version 1.2 or later. You should have received a copy of
    the english license text with the software. For your rights and
    obligations under this license refer to the file LICENSE or visit
    https://joinup.ec.europa.eu/community/eupl/og_page/eupl to view
    official translations of the licence in another language of the EU.
--->

# Mendeley Watchdog ![pipeline-checks][badge-checks]

Mendeley Watchdog is a command line utility that continuously watches the last
modification time of a given files and writes the content to a specified file.

**WARNING** The contents of the specified destination file are not checked
            checked before they are overwritten. Therefore the contents of
            the destination file will always be overwritten after the first
            "check". All manual changes to the destination file will always
            be overwritten when a change to the source file was detected.

**WARNING** The file contents are read and written in binary mode, as of
            right now this behavior can not be changed. This may be changed
            in future versions of this software.

The motivation for this software arose from the need to be able to save BibTeX
files that are managed by [Mendeley Desktop][mendeley-desktop] to LaTeX project
directories. While Mendeley does support creating BibTeX files on a per-project
basis it does not allow setting specific directories to which the individual
files are saved. They are all written to the same directory. This software

The first (an so far only) entry point for the software fulfills that need by
making it possible to mirror one of these files to any writable destination.
Since I write LaTeX using Visual Studio Code I wanted to be able to run the
monitoring process whenever the workspace folder for a project is open. Luckily
VS Code makes it possible to configure arbitrary tasks for a given workspace.
The **mendeley-watchdog** entry point was designed with this use-case in mind, an
exemplary task could look like this:
```
{
    "label": "Mirror hhn-it-systems",
    "type": "shell",
    "command": "mendeley-watchdog",
    "runOptions": {"runOn": "folderOpen"},
    "problemMatcher": ["$eslint-compact"],
    "args": [
        "--mendeley-bibtex",
        "'R:\\Mendeley Library\\.bib'",
        "hhn-it-systems.bib",
        "resources/references.bib"
    ]
}
```
The above task launches **mendeley-watchdog** as soon as the containing
workspace folder is opened. The task continuously mirrors the file
*R:\Mendeley Library\.bib\hhn-it-systems.bib* as *references.bib* to the
workspace subdirectory *resources*. Refer to the [documentation][toc-doc] for a
more detailed explanation of the entry point and task.

## Installation
The above-mentioned VS Code task assumes the entry point is on PATH. An easy
way to achieve this is installing via **[pipx][pipx]** which isolates the
package in its own virtual environment exposes their entry points on PATH.
```
pipx install mendeley-watchdog
```
Alternatively install using
```
pip install mendeley-watchdog
```

## Documentation
The detailed [documentation for mendeley-watchdog][master-docs] can be found on
GitHub. Be aware that the above link points to the master branch. If you're
reading this on PyPI that means it might be outdated. In that case use the
*Documentation* URL from the sidebar which should point towards the latest
release docs.

## Further Development
Depending on usefulness (and reception) additional functionality may be added.
Ideas include:
- enable mirroring any single file (not just bib files)
    - allow mirroring a single watched file to multiple destinations
- enable mirroring a map of files and destinations

Feel free to [open an issue][new-issue] if you encountered bugs or have other
ideas that aren't yet listed in the [backlog][issues].


[badge-checks]: https://github.com/vlntnwbr/mendeley-watchdog/workflows/checks/badge.svg
[toc-doc]: #documentation

[mendeley-desktop]: https://www.mendeley.com/reference-management/mendeley-desktop
[pipx]: https://pypi.org/project/pipx/
[master-docs]: https://github.com/vlntnwbr/mendeley-watchdog/tree/master/docs
[new-issue]: https://github.com/vlntnwbr/mendeley-watchdog/issues/new/choose
[issues]: https://github.com/vlntnwbr/mendeley-watchdog/issues


