update readme
This commit is contained in:
Dima Gerasimov
parent
ea00c2afdb
commit
185fa9aabd
2 changed files with 58 additions and 28 deletions
|
|
@ -13,7 +13,7 @@ I understand people may not super familiar with Python, PIP or generally unix, s
|
|||
- similarly, I'm using =python3= in the documentation, but if your =python --version= says python3, it's okay to use =python=
|
||||
|
||||
- when you use ~pip install~, [[https://stackoverflow.com/a/42989020/706389][always pass =--user=]]
|
||||
- I'm assuming the config directory is =~/.config=, but it's different on Mac/Windows.
|
||||
- throughout the guide I'm assuming the config directory is =~/.config=, but it's different on Mac/Windows.
|
||||
|
||||
See [[https://github.com/ActiveState/appdirs/blob/3fe6a83776843a46f20c2e5587afcffe05e03b39/appdirs.py#L187-L190][this]] if you're not sure what's your user config dir.
|
||||
|
||||
|
|
@ -22,8 +22,13 @@ This is a *required step*
|
|||
|
||||
You can choose one of the following options:
|
||||
|
||||
** install from [[https://pypi.org/project/HPI][PIP]]
|
||||
This is the easiest way:
|
||||
|
||||
: pip3 install --user HPI
|
||||
|
||||
** local install
|
||||
This is the most convenient option at the moment:
|
||||
This is convenient if you're planning to add new modules or change the existing ones.
|
||||
|
||||
1. Clone the repository: =git clone git@github.com:karlicoss/HPI.git /path/to/hpi=
|
||||
2. Go into the project directory: =cd /path/to/hpi=
|
||||
|
|
@ -54,25 +59,46 @@ This is less convenient, but gives you more control.
|
|||
|
||||
The benefit of this way is that you get a bit more control, explicitly allowing your scripts to use your data.
|
||||
|
||||
** install from PIP
|
||||
|
||||
This is still work in progress!
|
||||
|
||||
* Setting up the modules
|
||||
This is an *optional step* as some modules might work without extra setup.
|
||||
But it depends on the specific module.
|
||||
|
||||
** private configuration (=my.config=)
|
||||
# TODO update this section..
|
||||
# TODO write aobut dynamic configuration
|
||||
If you're not planning to use private configuration (some modules don't need it) you can skip straight to the next step. Still, I'd recommend you to read anyway.
|
||||
|
||||
First you need to tell the package where to look for your data and external repositories, which is done though a separate (private) package named ~mycfg~.
|
||||
The configuration contains paths to the data on your disks, links to external repositories, etc.
|
||||
|
||||
You can see example in ~mycfg_template~. You can copy it somewhere else and modify to your needs.
|
||||
By default, your config is expected in =~/.config/my=. For example, mine looks like:
|
||||
|
||||
Some explanations:
|
||||
#+begin_src python :exports results :results output
|
||||
from pathlib import Path
|
||||
home = Path("~").expanduser()
|
||||
pp = home / '.config/my/my/config'
|
||||
for p in sorted(pp.rglob('*')):
|
||||
if '__pycache__' in p.parts:
|
||||
continue
|
||||
ps = str(p).replace(str(home), '~')
|
||||
print(ps)
|
||||
#+end_src
|
||||
|
||||
#+RESULTS:
|
||||
#+begin_example
|
||||
~/.config/my/my/config/__init__.py
|
||||
~/.config/my/my/config/locations.py
|
||||
~/.config/my/my/config/repos
|
||||
~/.config/my/my/config/repos/endoexport
|
||||
~/.config/my/my/config/repos/fbmessengerexport
|
||||
~/.config/my/my/config/repos/kobuddy
|
||||
~/.config/my/my/config/repos/monzoexport
|
||||
~/.config/my/my/config/repos/pockexport
|
||||
~/.config/my/my/config/repos/rexport
|
||||
#+end_example
|
||||
|
||||
You can see an example in [[file:../mycfg_template][~mycfg_template~]]:
|
||||
|
||||
#+begin_src bash :exports results :results output
|
||||
cd ..
|
||||
for x in $(find mycfg_template/ | grep -v -E 'mypy_cache|.git|__pycache__|scignore'); do
|
||||
if [[ -L "$x" ]]; then
|
||||
echo "l $x -> $(readlink $x)"
|
||||
|
|
@ -88,25 +114,28 @@ Some explanations:
|
|||
#+RESULTS:
|
||||
#+begin_example
|
||||
d mycfg_template/
|
||||
d mycfg_template/mycfg
|
||||
f mycfg_template/mycfg/__init__.py
|
||||
d mycfg_template/my
|
||||
d mycfg_template/my/config
|
||||
f mycfg_template/my/config/__init__.py
|
||||
---
|
||||
class paths:
|
||||
"""
|
||||
Feel free to remove this if you don't need it/add your own custom settings and use them
|
||||
"""
|
||||
|
||||
class hypothesis:
|
||||
export_path = '/tmp/my_demo/backups/hypothesis'
|
||||
# expects outputs from https://github.com/karlicoss/hypexport
|
||||
# (it's just the standard Hypothes.is export format)
|
||||
export_path = '/path/to/hypothesis/data'
|
||||
---
|
||||
d mycfg_template/mycfg/repos
|
||||
l mycfg_template/mycfg/repos/hypexport -> /tmp/my_demo/hypothesis_repo
|
||||
d mycfg_template/my/config/repos
|
||||
l mycfg_template/my/config/repos/hypexport -> /tmp/my_demo/hypothesis_repo
|
||||
#+end_example
|
||||
|
||||
As you can see, generally you specify fixed paths (e.g. to backup directory) in ~__init__.py~.
|
||||
Feel free to add other files as well though to organize better, it's a real python package after all!
|
||||
As you can see, generally you specify fixed paths (e.g. to your backups directory) in ~__init__.py~.
|
||||
Feel free to add other files as well though to organize better, it's a real Python package after all!
|
||||
|
||||
Some things (e.g. links to external packages like [[https://github.com/karlicoss/hypexport][hypexport]]) are specified as normal symlinks in ~repos~ directory.
|
||||
That way you get easy imports (e.g. =import mycfg.repos.hypexport.model=) and proper IDE integration.
|
||||
Some things (e.g. links to external packages like [[https://github.com/karlicoss/hypexport][hypexport]]) are specified as ordinary symlinks in ~repos~ directory.
|
||||
That way you get easy imports (e.g. =import my.config.repos.hypexport.model=) and proper IDE integration.
|
||||
|
||||
# TODO link to post about exports?
|
||||
** module dependencies
|
||||
|
|
@ -122,7 +151,7 @@ Polar doesn't require any setup as it accesses the highlights on your filesystem
|
|||
|
||||
You can try if it works with:
|
||||
|
||||
: with_my python3 -c 'import my.reading.polar as polar; print(polar.get_entries())'
|
||||
: python3 -c 'import my.reading.polar as polar; print(polar.get_entries())'
|
||||
|
||||
** Kobo reader
|
||||
Kobo provider allows you access the books you've read along with the highlights and notes.
|
||||
|
|
@ -140,7 +169,7 @@ It uses exports provided by [[https://github.com/karlicoss/kobuddy][kobuddy]] pa
|
|||
After that you should be able to use it:
|
||||
|
||||
#+begin_src bash
|
||||
with_my python3 -c 'import my.books.kobo as kobo; print(kobo.get_highlights())'
|
||||
python3 -c 'import my.books.kobo as kobo; print(kobo.get_highlights())'
|
||||
#+end_src
|
||||
|
||||
** Orger
|
||||
|
|
@ -154,7 +183,7 @@ Some examples (assuming you've [[https://github.com/karlicoss/orger#installing][
|
|||
|
||||
This will convert Polar highlights into org-mode:
|
||||
|
||||
: with_my orger/modules/polar.py --to polar.org
|
||||
: orger/modules/polar.py --to polar.org
|
||||
|
||||
** =demo.py=
|
||||
read/run [[../demo.py][demo.py]] for a full demonstration of setting up Hypothesis (it uses public annotations data from Github)
|
||||
|
|
|
|||
3
setup.py
3
setup.py
|
|
@ -4,7 +4,8 @@
|
|||
from setuptools import setup, find_packages # type: ignore
|
||||
|
||||
INSTALL_REQUIRES = [
|
||||
'appdirs'
|
||||
'appdirs',
|
||||
'pytz', # even though it's not needed by the core, it's so common anyway...
|
||||
]
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue