Merge pull request #7 from mivanit/reorg-setup-dev

reverting part of interface, major reorg, created `setup.py`

.gitignore

@@ -6,6 +6,8 @@ examples/**
 examples/vault/**
 !examples/vault/*.md
 
+env/**
+
 .vscode/**
 
 # default python ignores

Makefile

@@ -0,0 +1,80 @@
+SOURCE = $(wildcard dendron_citations/*.py)
+ENV = env
+
+# block separator
+BSP = "======================================================================"
+
+PYLINT_OPTIONS = --disable=invalid-name,bad-indentation,use-list-literal,use-dict-literal,superfluous-parens,trailing-whitespace,trailing-newlines,too-many-instance-attributes
+
+# detecting os
+ifeq ($(OS),Windows_NT)
+	detected_os = Windows
+	FLAG_PTHREAD = -lpthread
+else
+	detected_os = Linux
+	FLAG_PTHREAD = -pthread
+endif
+
+
+.PHONY: setup_env
+setup_env:
+	@echo "# set up virtual environment, installing dependecies and the package"
+
+	@printf "$(BSP)\n# setting up virtual environment  \n$(BSP)\n"
+	python -m venv env
+
+	@printf "$(BSP)\n# installing package dependencies  \n$(BSP)\n"
+	$(ENV)/Scripts/pip install -r requirements.txt
+
+	@printf "$(BSP)\n# installing dev dependencies  \n$(BSP)\n"
+	$(ENV)/Scripts/pip install -r requirements_dev.txt
+
+	@printf "$(BSP)\n# installing package  \n$(BSP)\n"
+	$(ENV)/Scripts/pip install -e .
+
+	@printf "$(BSP)\n# installation complete!  \n$(BSP)\n"
+
+.PHONY: env_clean
+env_clean:
+	@echo "# clean up the existing virtual environment"
+
+	rm -rf $(ENV)/
+
+.PHONY: check
+check:
+	@echo "# run mypy, pylint"
+
+	@echo "# will run on files:"
+	@echo "$(SOURCE)"
+
+	@printf "$(BSP)\n# running mypy  \n$(BSP)\n"
+	-$(ENV)/Scripts/mypy $(SOURCE)
+
+	@printf "$(BSP)\n# running pylint  \n$(BSP)\n"
+	-$(ENV)/Scripts/pylint $(SOURCE) $(PYLINT_OPTIONS)
+
+	@printf "$(BSP)\n# type checking complete!  \n$(BSP)\n"
+
+# @echo "$(BLOCKSEP)"
+# @echo "# running pytype"
+# @echo "$(BLOCKSEP)"
+# -pytype $(SOURCE)
+
+
+
+
+
+
+# listing targets, from stackoverflow
+# https://stackoverflow.com/questions/4219255/how-do-you-get-the-list-of-targets-in-a-makefile
+.PHONY: help
+help:
+	@echo -n "# Common make targets"
+	@echo ":"
+	@cat Makefile | sed -n '/^\.PHONY: / h; /\(^\t@*echo\|^\t:\)/ {H; x; /PHONY/ s/.PHONY: \(.*\)\n.*"\(.*\)"/    make \1\t\2/p; d; x}'| sort -k2,2 |expand -t 20
+
+	@echo "# detected source files:"
+	@echo "    $(SOURCE)"
+
+	@echo "# activate env using:"
+	@echo "    source $(ENV)/Scripts/activate"

README.md

@@ -4,39 +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`](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: 
 
-- `gen` : generate reference notes:
+# Contents:
+- [Usage](#usage)
+- [Installation](#installation)
+- [Extras](#extras)
+- [Roadmap](#roadmap)
+
+
+
+# Usage: 
+
+to generate reference notes, run from anywhere:
 
 ```bash
-python refs_vault_gen.py gen [cfg_path] [kwargs]
+dendron_gen_refs.py [cfg_path] [--<kwarg>=<val>]
 ```
 
-- `help` : print help message and exit:
+## 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:
+- `--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 gen [cfg_path] [**kwargs]
+dendron_gen_refs.py [cfg_path] [**kwargs]
 ```
 
 `cfg_path` should be the location of a yaml or json config file
@@ -54,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!
@@ -81,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`](md_util.py) and [`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
@@ -117,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
 
@@ -131,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`