Merge pull request #186 from vict0rsch/mkdocs

vict0rsch · Nov 20, 2023 · 14bbc8f · 14bbc8f
2 parents d12bfe2 + 2c5ac7d
commit 14bbc8f
Show file tree

Hide file tree

Showing 102 changed files with 9,169 additions and 310 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -0,0 +1,30 @@
+name: ci
+on:
+  push:
+    branches:
+      - master
+      - main
+      - mkdocs
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install "mkdocs-material[imaging]"
+      - run: mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
@@ -7,4 +7,5 @@ keys.json
 test/tmp/
 *.lock
 .nyc_output/
-coverage
+coverage
+.cache
diff --git a/CNAME b/CNAME
@@ -0,0 +1 @@
+papermemory.org
diff --git a/Readme.md b/Readme.md
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,21 @@
+---
+description: About PaperMemory and its developper.
+---
+
+# About PaperMemory
+
+PaperMemory is developped as a Free and Open Software by [vict0rsch](https://vict0rs.ch).
+
+Share ideas 💡 or bugs 🐛 in [issues](https://github.com/vict0rsch/PaperMemory/issues) and love with [stars](https://github.com/vict0rsch/PaperMemory/stargazers) ⭐️ 😃.
+
+## If you like PaperMemory
+
+* Share a [nice word ❤️‍🔥](https://github.com/vict0rsch/PaperMemory/issues/81)
+* Star ⭐ the [project](https://github.com/vict0rsch/PaperMemory)
+* Advocate for PaperMemory on social media [:fontawesome-brands-square-x-twitter: `#PaperMemory - @vict0rsch`](https://x.com/vict0rsch) and around you in your lab or team.
+* Rate on the webstore [:fontawesome-brands-chrome: / :simple-brave: / :fontawesome-brands-edge:](https://chromewebstore.google.com/detail/paper-memory/hmebhknlgddhfbbdhgplnillngljgmdi?pli=1) or [:fontawesome-brands-firefox-browser:](https://addons.mozilla.org/en-US/firefox/addon/paper-memory/)
+* [☕ Buy me a coffe](https://www.buymeacoffee.com/vict0rsch)
+
+## If you want to help
+
+I'm always looking for feedback, beta-testers or help with the development (:simple-javascript: / :simple-html5: / :simple-css3:). Do reach out @ `vsch [at] pm [dot] me` or in [issues](https://github.com/vict0rsch/PaperMemory/issues), there's often some low hanging fruit which need help with. Or contribute your own ideas in a :material-source-pull: PR :mechanical_arm:.
diff --git a/docs/assets/advanced.png b/docs/assets/advanced.png
diff --git a/docs/assets/bibMatcher.gif b/docs/assets/bibMatcher.gif
diff --git a/docs/assets/bolt-white.svg b/docs/assets/bolt-white.svg
diff --git a/docs/assets/d2.gif b/docs/assets/d2.gif
diff --git a/docs/assets/display.png b/docs/assets/display.png
diff --git a/docs/assets/dm.png b/docs/assets/dm.png
diff --git a/docs/assets/favicon-192x192.png b/docs/assets/favicon-192x192.png
diff --git a/docs/assets/home_slideshow.gif b/docs/assets/home_slideshow.gif
diff --git a/docs/assets/memory.png b/docs/assets/memory.png
diff --git a/docs/assets/menu.png b/docs/assets/menu.png
diff --git a/docs/assets/paper.png b/docs/assets/paper.png
diff --git a/docs/assets/popup.png b/docs/assets/popup.png
diff --git a/docs/assets/sync.png b/docs/assets/sync.png
diff --git a/docs/assets/website.gif b/docs/assets/website.gif
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,179 @@
+---
+description: PaperMemory's configuration and documentation.
+icon: octicons/gear-16
+---
+
+# Configuring PaperMemory
+
+## Keyboard Shortcuts
+
+By default, and _if_ they are not already attributed, the following keyboard shortcuts are available:
+
+* ++cmd+shift+"E"++ will open PaperMemory's popup on a **Mac**, ++ctrl+shift+"M"++ on **Linux & Windows**.
+* ++cmd++ / ++ctrl++ + ++shift+"S"++ will try to download the pdf of the current paper. If you have enabled this feature in the menu, the paper will be downloaded in your PaperMemoryStore (see thee advanced options page for more info)
+* ++cmd++ / ++ctrl++ + ++shift+"L"++ will trigger the manual parsing of a paper if you have disabled automatic paper detection in the menu
+
+All those shortcuts can be changed/set from `chrome://extensions/shortcuts` (:fontawesome-brands-chrome: Chrome / :simple-brave: Brave / :fontawesome-brands-edge: Edge) or `about:addons` (:fontawesome-brands-firefox-browser: Firefox).
+
+### Keyboard Navigation
+
+Navigate the Popup with your keyboard:
+
+  * Open the Memory
+    * ++"A"++ from the popup's home will open it
+    * navigate to the bottom left button with ++tab++ and hit ++enter++
+  * Search
+    * Search field is automatically focused on memory open
+    * Navigate to the top input with ++tab++ or ++shift+tab++
+  * Navigate papers
+    * ++tab++ will iterate through papers down the list
+    * ++shift+tab++ will go back up the list
+  * Edit a paper
+    * Press ++e++ to _edit_ the paper's metadata: tags, code and note when the paper is *focused* (from click or keyboard ++tab++ navigation)
+      * Navigate through fields with (++shift++ +) ++tab++: tags and note if you're on a paper's page.
+    * Press ++enter++ to _open_ a focused paper (*focus* an existing tab with the paper or *create a new tab* to the paper's pdf if it's not open already)
+    * ++backspace++ to _delete_ a focused paper (a confirmation will be prompted first don't worry 👮‍♀️)
+  * Close Memory or Menu
+
+## Popup Menu
+
+
+<p align="center" markdown>
+![Popup](assets/popup.png){ align=left .popup-display }
+![Popup](assets/menu.png){ align=right .popup-display }
+</p>
+
+<p style="clear: both;"/>
+
+The following :fontawesome-solid-toggle-on: items are displayed in PaperMemory's :octicons-gear-16: Popup Menu and can be changed anytime (close and re-open popup to see changes).
+
+---
+
+### Arxiv enhancements
+
+`Add PDF direct download button`
+
+:   Add the blue animated button to download the PDF to your Downloads without opening it.
+
+`Add Markdown Link section`
+
+:   In the right-most column on ArXiv.org, add the copy-able box with a :material-language-markdown-outline: Markdown-ready link `[$title]($url)`.
+
+`Add BibTex citation section`
+
+:   In the right-most column on ArXiv.org, add the copy-able box with a :tabler-math-function: BibTex citation.
+
+---
+
+### User interface
+
+`Display notification when a paper is added`
+
+:   Enable/Disable the red sliding notification displayed by PaperMemory when a Paper is parsed or a new code repository is found.
+
+`Use Dark Mode`
+
+:   Choose between light and dark mode for the Popup, Advanced Options and BibMatcher.
+
+`Directly open the Memory when not on a Paper's page`
+
+:   This feature assumes that your primary reason to open PaperMemory -- when you're not on a paper's page -- is to look for a paper in your Memory and therefore directly opens it without you cliking on the :material-folder-multiple-outline: button or pressing ++a++.
+
+`Change paper tab titles`
+
+:   By default, PaperMemory will replace your browser's tab titles with the paper's title so they are more easily searched and bookmarked.
+
+`Add a link to SciRate in the popup`
+
+:   Add a :tabler-scirate: icon to your papers to open directly on [SciRate](https://scirate.com).
+
+`Add a link to arXiv Vanity in the popup`
+
+:   Add a :tabler-arxiv-vanity: icon to your papers to open directly on [ArXiv Vanity](https://www.arxiv-vanity.com/).
+
+`Add a link to ar5iv in the popup`
+
+:   Add a :tabler-ar5iv: icon to your papers to open directly on [ar5iv](https://ar5iv.labs.arxiv.org/).
+
+`Add a link to the HuggingFace paper page in the popup (Arxiv only)`
+
+:   Add a :tabler-hf-logo-transparent-darktheme: icon to your papers to open directly on [HuggingFace Papers](https://huggingface.co/papers).
+
+
+### Functionalities
+
+`Include a paper's venue and year when available in the Markdown link`
+
+:   Choose between `[$title]($url)` and `[$title -- $venue ($year)]($url)` when creating the :material-language-markdown-outline: Markdown links for a paper (only if a venue is known).
+
+`Favor PDFs for paper links (otherwise, links will point to a paper's abstract page)`
+
+:   Whenever a link is involved (:material-language-markdown-outline:, :tabler-external-link:, :octicons-link-24: etc.) prefer linking to the online PDF (if known) over the default HTML/Abstract page.
+
+`Only record papers on their pdf pages, not from their abstracts`
+
+:   Prevent PaperMemory from recording *all* papers, but only those of which you open the PDF.
+
+`Disable automatic recording of papers. You will have to manually open the popup and click a button`
+
+:   Prevent PaperMemory from recording *any* paper, you will have to trigger the parsing from the Popup or the [Keyboard Shortcut](./configuration.md#keyboard-shortcuts).
+
+`When hitting Enter on a memory item, open a local PDF file when one is available instead of the the link to the paper.`
+
+:   Choose to open the local PDF file you have in your `Downloads/` (if any) instead of opening the online version of the PDF, when pressing ++enter++ on a paper in your Memory.
+
+`Download pdfs to PaperMemory's folder in your Downloads to be able to open them instead of re-downloading.`
+
+:   Enable the `PaperMemoryStore/` folder in your `Downloads/` to enable PaperMemory to handle local files instead of re-downloading online PDFs every time.
+
+`Enable parsing of arbitrary website by adding a button in the popup.`
+
+:   Adds the `Parse Current Website` button when on an unknown web page (*i.e.* not detected as a paper provider) to record arbitrary web pages to your Memory.
+
+## Advanced Options
+
+<p align="center" markdown>
+![Popup](assets/advanced.png){ .advanced-screenshot }
+</p>
+
+More customization options and features are available in the **Advanced Options page**:
+
+* Right click on the extension's button in your browser toolbar and select *Options*
+* Open the Popup Menu, scroll down and click on *Options page*.
+* Paste one of those URLs in your address bar
+  ```bash
+  # Chrome / Brave / Edge:
+  chrome-extension://ehchlpggdaffcncbeopdopnndhdjelbc/src/options/options.html
+  # Firefox:
+  moz-extension://05b6ef8a-7314-4c1d-a519-80f48a5794a6/src/options/options.html
+  ```
+
+
+`PapersWithCode preferences`
+
+:    Choose whether or not you enable unofficial repositories and if you have a preferred (Tensorflow / PyTorch) Deep Learning framework.
+
+`Auto-tagging`
+
+:   Define a list of regexs to apply to `title` and `author` fields to automatically tag papers in your Memory.
+
+`Preprint matching`
+
+:   Trigger the preprint-matching process for your current memory: this will search for published versions of your ArXiv preprints. PaperMemory will continuously look for publications when you visit a preprint's ArXiv page, but this feature bulks the process for all preprints in your memory.
+
+`Select Sources`
+
+:   Select the paper sources you want PaperMemory to parse papers from.
+
+`Data Management`
+
+:   Manage your data:
+
+    * export your memory as `.bib` or `.json` files
+    * import an existing `.json` memory you have backed-up
+    * export a bibliography by tag
+    * import a list of URLs into your memory.
+
+`Online synchronization`
+
+:   Enable [Online Synchronization](features.md#online-synchronization) by providing a Github Personal Access Token.
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,89 @@
+---
+description: PaperMemory's Frequently Asked Questions
+---
+
+# FAQ
+
+
+### Why does PaperMemory require access to all urls?
+
+Because Chrome & Brave will disable an extension by default when it auto-updates with new permissions. In this case, any new addition of a paper source will require new permissions to access the data necessary to parse the paper data and will therefore disable the extension until users re-enable it.
+
+### The button to go from an abstract to its pdf does not work
+
+In general there can be 2 reasons:
+
+1. It's a bug, it can happen, I'm sorry about this: you should raise an issue, and ideally even provide a fix in a Pull Resquest
+2. More likely, the pdf is behind a paywall and the standard `abstract -> pdf` path was redirected by the venue's website
+
+
+### How do you match Arxiv.org pre-prints to actual publications?
+
+
+It's all there: [preprints](features.md#preprint-matching) 😃
+
+Contributions and ideas on how to improve the process and potentially add publication sources from titles or arxiv `id` are welcome!
+
+### Where does PaperMemory store my data?
+
+It's all stored locally in your browser's local storage. If you want to transfer data to a new browser/computer, use the export/import tools in the extension's options.
+
+### How can I export all or some papers?
+
+Check out the [Advanced Options](./configuration.md#advanced-options)'s *Data Management* section, you can export:
+
+* your full PaperMemory data as `.json` file
+* your full bibliography as `.bib`  file (or `.json`)
+* papers based on the tags you'be assigned them as a `.bib` file
+
+### Can I reference my PDF in PaperMemory?
+
+If you want to associate a PDF file to a paper in your PaperMemoryStore that is not downloaded from PaperMemory (for instance, it is behind a paywall), you can **download it to `~/Downloads/PaperMemoryStore/`** (maybe you're reading the paper on Sci-Hub you thief 🙃) provided the file's name contains the **paper's title** (not counting non-alphanumeric characters and case-insensitive).
+
+Because of limitations Browser Extensions face, a file **must** be _downloaded from the Browser to the folder_ in order to be detected. This means that if someone sends you a pdf over Slack or if you move a file to the PaperMemoryStore folder for instance, you won't be able to match it to a PaperMemory item.
+
+### How do I resolve duplicates?
+
+* If you installed PaperMemory `<0.5.3` (May 2022) you may have duplicate papers in your Memory. The easiest way to resolve this is to go to a duplicate's page, then delete it from memory and refresh the page. The automatic de-duplication features in version `0.5.3` should handle the matching _if_ the 2 papers have the same title.
+* If you still see duplicates with PaperMemory `>=0.5.3` _and_ the 2 papers have the same title, this may be a problem with PaperMemory and you should open an issue here on Github.
+
+
+### Can I access the memory full-screen?
+
+Sure! In the extension popup's menu, there's a link at the bottom to the full-page memory. You can also just go to this url (Thanks @kaixin96!):
+
+```bash
+# Copy-paste this url (Chrome / Brave / Edge):
+chrome-extension://ehchlpggdaffcncbeopdopnndhdjelbc/src/fullMemory/fullMemory.html
+# Firefox:
+moz-extension://05b6ef8a-7314-4c1d-a519-80f48a5794a6/src/fullMemory/fullMemory.html
+```
+
+### Can I exclude a paper source?
+
+Yep. In the extension popup's advanced options page: right-click the extension's icon and click on `Options`. Or click on the link at the bottom of the popup menu. Or go to this url (Thanks @kaixin96!):
+
+```bash
+# Copy-paste this url (Chrome / Brave / Edge):
+chrome-extension://ehchlpggdaffcncbeopdopnndhdjelbc/src/options/options.html
+# Firefox:
+moz-extension://05b6ef8a-7314-4c1d-a519-80f48a5794a6/src/options/options.html
+```
+
+### Are there data backups?
+
+In case there's a bad bug or you mess up when overwriting your memory, PaperMemory preforms weekly backups (locally as always), which you can retrieve with a little coding:
+
+1. Open the extension's options (either right clicking its icon, or from the extension's menu, at the bottom)
+2. On the options page, open the Javascript Console with `cmd/ctrl + alt + i` or `right click > Inspect`
+3. Do the following in the Javascript Console:
+
+```javascript
+const backups = await getStorage("weeklyBackups")
+console.log(Object.keys(backups)) // this shows you available backup dates
+const overwrite = backups["<some key from above>"]
+console.log(overwrite) // inspect this and make sure it is what you want
+setStorage("papers", overwrite) // Careful! This will overwrite the current data with the backup data
+```
+
+Note that if you uninstall PaperMemory all your data will be gone and the only way to keep track of what was in your Memory is to export it first (in the advanced options page).