update readme

README.md

@@ -4,48 +4,47 @@ tool for making [Dendron](https://www.dendron.so) work well with citing things u
 
 WORK IN PROGRESS. please use with care, since this will overwrite files in your dendron vault
 
-
-# [`refs_vault_gen.py`](dendron_citations/refs_vault_gen.py)
-
-generates a vault of dendron notes corresponding to entries from a bibtex file
+The main script is [`dendron_gen_refs.py`](scripts/dendron_gen_refs.py), which generates a vault of dendron notes corresponding to entries from a bibtex file
 
 this allows the user to reference the dendron notes instead of raw bibtex item (such as when using [PandocCiter](https://github.com/notZaki/PandocCiter)), which lets us use backlink features from dendron to see where we have cited a paper
 
 > Note: I personally put all my references in a separate vault from my main vault, to avoid clutter. I highly recommend this, since this *might* also prevent you from accidentally overwriting things in your main vault.
 
-## Usage: 
 
-generate reference notes:
+# Contents:
+- [Usage](#usage)
+- [Installation](#installation)
+- [Extras](#extras)
+- [Roadmap](#roadmap)
 
-```bash
-python refs_vault_gen.py [cfg_path] [--<kwarg>=<val>]
-```
 
-`cfg_path` can be positional. If arguments are passed, the defaults are used. Notably:
-```python
-bib_filename : str = 'refs.bib'
-vault_loc : str = 'vault/'
-note_prefix : str = 'refs.'
+
+# Usage: 
+
+to generate reference notes, run from anywhere:
+
+```bash
+dendron_gen_refs.py [cfg_path] [--<kwarg>=<val>]
 ```
 
-### Help and configuration
+## Help and configuration
 
 - `--help` : print help message and exit:
 ```bash
-python refs_vault_gen.py --help
+dendron_gen_refs.py --help
 ```
 
 - `--print_cfg` : print to console an example config in either json or yaml (json by default):
 
 ```bash
-python refs_vault_gen.py --print_cfg [--fmt=<format>]
+dendron_gen_refs.py --print_cfg [--fmt=<format>]
 ```
 
-### Generation:
+## Generation:
 
 when running
 ```bash
-	python refs_vault_gen.py [cfg_path] [**kwargs]
+dendron_gen_refs.py [cfg_path] [**kwargs]
 ```
 
 `cfg_path` should be the location of a yaml or json config file
@@ -63,20 +62,49 @@ the expected config elements, types, and default values are:
 	template_path : Optional[str] = None
 ```
 
-### Examples:
+## Examples:
 
 ```bash
-python refs_vault_gen.py gen --bib_filename=<bibtex_file> --vault_loc=<output_dir>
+dendron_gen_refs.py gen --bib_filename=<bibtex_file> --vault_loc=<output_dir>
 ```
 
 Or, we could create a config file such as [`examples/custom_cfg.json`](examples/custom_cfg.json) and pass it in as
 ```bash
-python refs_vault_gen.py gen <path_to_config_file>
+dendron_gen_refs.py gen <path_to_config_file>
 ```
 
 > **Note:** if you pass a config file, the script will change its directory to that of the config file, to allow paths to be specified relative to that file.
 
 
+
+# Installation:
+
+Not yet on [PyPi](https://pypi.org/), due to instability. you can install with
+```bash
+pip install -e git+https://github.com/mivanit/dendron-citations.git#egg=dendron_citations
+```
+
+Note that this will place an executable `dendron_gen_refs.py` in your python `Scripts` folder (and thus hopefully in your path).
+
+## Dependencies:
+
+- https://github.com/t-wissmann/biblib
+	- not on pypi, installed from git repo
+	- note: forked from https://github.com/aclements/biblib, which no longer works
+- [`pyyaml`](https://github.com/yaml/pyyaml/)
+- [`chevron`](https://github.com/noahmorrison/chevron)
+	- python implementation of the [mustache](https://mustache.github.io) templating language
+- [`pypandoc`](https://github.com/NicklasTegner/pypandoc) (optional)
+	- for converting notes to markdown
+
+
+
+
+
+
+
+# Extras
+
 ## tag notes
 
 Not only can we use dendron backlinks to view where we have cited a certain paper, but we can additionally use the backlinks to see all papers by a given author, or all papers with a given keyword!
@@ -90,31 +118,36 @@ For now, you need to manually modify the template string `DEFAULT_TEMPLATE` in t
 - Add the prefix `_bln_` to the name of any iterable variable to get access to a boolean value that is true if the variable is not empty
 - Lists of non-dict items are turned into lists of dicts, where each dict has a single key `elt` with the value of the item
 
+For example, if `keywords` is a list of strings `['a', 'b']`, we can use the template
+```mustache
+{{#_bln_keywords}}# Keywords
+{{/_bln_keywords}}
+{{#keywords}}
+ - #{{elt}}
+{{/keywords}}
+```
 
-# Installation:
-
-not yet on pypi. for now, you just need the files [`md_util.py`](dendron_citations/md_util.py) and [`redendron_citations/refs_vault_gen.py(refs_vault_gen.py) somewhere, along with the dependencies listed below. This is a WORK IN PROGRESS, so I haven't put much work into streamlining installation.
-
-you can install the requirements with
-```bash
-pip install -r requirements.txt
+to print
+```markdown
+# Keywords
+ - a
+ - b
 ```
 
-## Dependencies:
+or to return an empty string (with newlines) if `keywords` is empty.
+
 
-- https://github.com/t-wissmann/biblib
-	- not on pypi, installed from git repo
-	- note: forked from https://github.com/aclements/biblib, which no longer works
-- [`pyyaml`](https://github.com/yaml/pyyaml/)
-- [`chevron`](https://github.com/noahmorrison/chevron)
-	- python implementation of the [mustache](https://mustache.github.io) templating language
-- [`pypandoc`](https://github.com/NicklasTegner/pypandoc) (optional)
-	- for converting notes to markdown
 
 
 
 # Roadmap:
 
+## general
+- [x] implement a configuration system
+- [x] set up as an installable package
+- [ ] turn this into a real vscode plugin
+	- will probably use [`vscode-ext`](https://github.com/CodeWithSwastik/vscode-ext)
+
 ## bibtex integration
 
 - [x] given a bibtex file, generate a vault of dendron notes bibtex keys as filenames
@@ -126,9 +159,6 @@ pip install -r requirements.txt
 	- this will allow for better searching for papers
 - [ ] make citations work properly when compiling with [Pandoc](https://pandoc.org/)
 	- probably best to do this as part of [dendron-pandoc](https://github.com/mivanit/dendron-pandoc)
-- [ ] turn this into a real vscode plugin
-	- mostly to simplify installation 
-	- will probably use [`vscode-ext`](https://github.com/CodeWithSwastik/vscode-ext)
 
 ## zotero integration
 
@@ -140,6 +170,17 @@ do everything as for bibtex integration, but also:
 	- links to all other attachments
 	- exclude the dendron file to avoid recursion, haha
 
+
+# Developing:
+
+After cloning, run
+```bash
+make help
+```
+to see some utilities for developing (setting up a virtual environment, running type and style checkers, etc.)
+
+
+
 # Misc
 
 - to allow simpler references to papers in a separate vault, without having to type `[[dendron://refs-vault/<bibtex key>]]`, the user may create a vscode snippet in `> Preferences > Configure User Snippets > markdown.json`