docs: Add formatting documentation

Added documentation on using output templates and that they will
invalidate the 'existing' annotation search.
This commit is contained in:
Marty Oehme 2023-09-20 09:03:08 +02:00
parent e511ffa48d
commit 3670f70319
Signed by: Marty
GPG key ID: EDBF2ED917B2EF6A
2 changed files with 27 additions and 4 deletions

View file

@ -11,7 +11,7 @@ Easily organize all your highlights and thoughts next to your documents and refe
## Installation:
<!-- TODO set up pypi repository / explain git install path -->
You can install from pypi with `pip install git+https://git.martyoeh.me/Marty/papis-extract.git`.
You can install through pip with `pip install git+https://git.martyoeh.me/Marty/papis-extract.git`.
That's it! If you have papis and papis-extract installed in the same environment (whether virtual or global),
everything should now be set up.
@ -87,6 +87,30 @@ On my current laptop, extracting ~4000 annotations from ~1000 library documents
though this will vary with the length and size of the PDFs you have.
For smaller workloads the process should be almost instant.
You can change the format that you want your annotations in with the `--template` option.
To output annotations in a markdown-compatible syntax (the default), do:
```bash
papis extract --template markdown
```
To instead see them in a csv syntax simply invoke:
```bash
papis extract --template csv
```
And if you only want to know how many annotations exist in the documents, you can invoke:
```bash
papis extract --template count
```
For now, these are the only formatters the plugin knows about.
Be aware that if you write to your notes using a different template the plugin will *not* detect old annotations and drop them,
so you will be doubling up your annotations.
## Configuration
### Basic configuration
@ -181,6 +205,8 @@ Known issues to be fixed:
- [x] docstrings, docstrings!
- [ ] testing testing testing!!
- [ ] refactor into some better abstractions (e.g. Exporter Protocol -> stdout/markdown implementations; Extractor Protocol -> PDF implementation)
- [ ] dependency injection for extractor/exporter/formatter/annotation modules
- [ ] any call to papis.config should start from init and be injected?
features to be implemented:

View file

@ -53,12 +53,9 @@ papis.config.register_default_settings(DEFAULT_OPTIONS)
)
def main(
query: str,
# info: bool,
# _papis_id: bool,
# _file: bool,
# notes: bool,
# _dir: bool,
# _format: str,
_all: bool,
doc_folder: str,
manual: bool,