Merge pull request #25 from karlicoss/updates

setup guide updates

doc/SETUP.org

@@ -12,8 +12,8 @@ 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.
+- when you are using ~pip install~, [[https://stackoverflow.com/a/42989020/706389][always pass]] =--user=
+- 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=
@@ -53,60 +58,86 @@ This is less convenient, but gives you more control.
    After that, you can wrap your command in =with_my= to give it access to ~my.~ modules, e.g. see [[#usage-examples][examples]].
 
 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=
 
-Some explanations:
+- For example, mine looks like:
 
-#+begin_src bash :exports results :results output
-  for x in $(find mycfg_template/ | grep -v -E 'mypy_cache|.git|__pycache__|scignore'); do
-    if   [[ -L "$x" ]]; then
-      echo "l $x -> $(readlink $x)"
-    elif [[ -d "$x" ]]; then
-      echo "d $x"
-    else
-      echo "f $x"
-      (echo "---"; cat "$x"; echo "---" ) | sed 's/^/  /'
-    fi
-  done
-#+end_src
+  #+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
-d mycfg_template/
-d mycfg_template/mycfg
-f mycfg_template/mycfg/__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'
-  ---
-d mycfg_template/mycfg/repos
-l mycfg_template/mycfg/repos/hypexport -> /tmp/my_demo/hypothesis_repo
-#+end_example
+  #+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
 
-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!
+- Another example is in [[file:../mycfg_template][mycfg_template]]:
 
-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.
+  #+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)"
+      elif [[ -d "$x" ]]; then
+        echo "d $x"
+      else
+        echo "f $x"
+        (echo "---"; cat "$x"; echo "---" ) | sed 's/^/  /'
+      fi
+    done
+  #+end_src
+
+  #+RESULTS:
+  #+begin_example
+  d mycfg_template/
+  d mycfg_template/my
+  d mycfg_template/my/config
+  f mycfg_template/my/config/__init__.py
+    ---
+    """
+    Feel free to remove this if you don't need it/add your own custom settings and use them
+    """
+
+    class 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/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 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 *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 +153,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.
@@ -130,8 +161,8 @@ It uses exports provided by [[https://github.com/karlicoss/kobuddy][kobuddy]] pa
 
 - prepare the config
 
-  1. Point  =ln -sfT /path/to/kobuddy ~/.config/my/config/repos/kobuddy=
-  2. Add kobo config to =~/.config/my/config/__init__.py=
+  1. Point  =ln -sfT /path/to/kobuddy ~/.config/my/my/config/repos/kobuddy=
+  2. Add kobo config to =~/.config/my/my/config/__init__.py=
     #+begin_src python
     class kobo:
         export_dir = 'path/to/kobo/exports'
@@ -140,7 +171,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 +185,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)

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...
 ]