Skip to content

Commit

Permalink
src/ doc links
Browse files Browse the repository at this point in the history
  • Loading branch information
PatMyron authored and karlicoss committed Feb 1, 2025
1 parent f8a55f7 commit 4910c86
Show file tree
Hide file tree
Showing 7 changed files with 73 additions and 73 deletions.
94 changes: 47 additions & 47 deletions README.org

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion doc/CONFIGURING.org
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ I feel like it's good to keep the rationales in the documentation,
but happy to [[https://github.com/karlicoss/HPI/issues/46][discuss]] it here.

Before discussing the abstract matters, let's consider a specific situation.
Say, we want to let the user configure [[https://github.com/karlicoss/HPI/blob/master/my/bluemaestro/__init__.py][bluemaestro]] module.
Say, we want to let the user configure [[https://github.com/karlicoss/HPI/blob/master/src/my/bluemaestro.py][bluemaestro]] module.
At the moment, it uses the following config attributes:

- ~export_path~
Expand Down
2 changes: 1 addition & 1 deletion doc/DENYLIST.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
For code reference, see: [`my.core.denylist.py`](../my/core/denylist.py)
For code reference, see: [`my.core.denylist.py`](../src/my/core/denylist.py)

A helper module for defining denylists for sources programmatically (in layman's terms, this lets you remove some particular output from a module you don't want)

Expand Down
2 changes: 1 addition & 1 deletion doc/DEVELOPMENT.org
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ and [[file:../scripts/ci/run]] for the up to date info on the specifics.
* IDE setup
To benefit from type hinting, make sure =my.config= is in your package search path.

In runtime, ~my.config~ is imported from the user config directory [[file:../my/core/init.py][dynamically]].
In runtime, ~my.config~ is imported from the user config directory [[file:../src/my/core/init.py][dynamically]].

However, Pycharm/Emacs or whatever IDE you are using won't be able to figure that out, so you'd need to adjust your IDE configuration.

Expand Down
32 changes: 16 additions & 16 deletions doc/MODULES.org
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ You don't have to set up all modules at once, it's recommended to do it graduall
For an extensive/complex example, you can check out ~@purarue~'s [[https://github.com/purarue/dotfiles/blob/master/.config/my/my/config/__init__.py][config]]

# Nested Configurations before the doc generation using the block below
** [[file:../my/reddit][my.reddit]]
** [[file:../src/my/reddit][my.reddit]]

Reddit data: saved items/comments/upvotes/etc.

Expand All @@ -104,7 +104,7 @@ For an extensive/complex example, you can check out ~@purarue~'s [[https://githu

#+end_src

** [[file:../my/browser/][my.browser]]
** [[file:../src/my/browser/][my.browser]]

Parses browser history using [[http://github.com/purarue/browserexport][browserexport]]

Expand All @@ -121,7 +121,7 @@ For an extensive/complex example, you can check out ~@purarue~'s [[https://githu
# export_path = Firefox.locate_database()
export_path: Paths
#+end_src
** [[file:../my/location][my.location]]
** [[file:../src/my/location][my.location]]

Merged location history from lots of sources.

Expand All @@ -130,7 +130,7 @@ For an extensive/complex example, you can check out ~@purarue~'s [[https://githu
google takeout (using =my.google.takeout.parser=), with a fallback on
manually defined home locations.

You might also be able to use [[file:../my/location/via_ip.py][my.location.via_ip]] which uses =my.ip.all= to
You might also be able to use [[file:../src/my/location/via_ip.py][my.location.via_ip]] which uses =my.ip.all= to
provide geolocation data for an IPs (though no IPs are provided from any
of the sources here). For an example of usage, see [[https://github.com/purarue/HPI/tree/master/my/ip][here]]

Expand All @@ -156,7 +156,7 @@ For an extensive/complex example, you can check out ~@purarue~'s [[https://githu
# guess ~15km accuracy for IP addresses
accuracy: float = 15_000
#+end_src
** [[file:../my/time/tz/via_location.py][my.time.tz.via_location]]
** [[file:../src/my/time/tz/via_location.py][my.time.tz.via_location]]

Uses the =my.location= module to determine the timezone for a location.

Expand Down Expand Up @@ -254,7 +254,7 @@ for cls, p in modules:

#+RESULTS:

** [[file:../my/google/takeout/parser.py][my.google.takeout.parser]]
** [[file:../src/my/google/takeout/parser.py][my.google.takeout.parser]]

Parses Google Takeout using [[https://github.com/purarue/google_takeout_parser][google_takeout_parser]]

Expand All @@ -278,7 +278,7 @@ for cls, p in modules:
# instead of unpacking to a tmp dir via match_structure
_use_zippath: bool = False
#+end_src
** [[file:../my/hypothesis.py][my.hypothesis]]
** [[file:../src/my/hypothesis.py][my.hypothesis]]

[[https://hypothes.is][Hypothes.is]] highlights and annotations

Expand All @@ -291,7 +291,7 @@ for cls, p in modules:
# paths[s]/glob to the exported JSON data
export_path: Paths
#+end_src
** [[file:../my/pocket.py][my.pocket]]
** [[file:../src/my/pocket.py][my.pocket]]

[[https://getpocket.com][Pocket]] bookmarks and highlights

Expand All @@ -304,7 +304,7 @@ for cls, p in modules:
# paths[s]/glob to the exported JSON data
export_path: Paths
#+end_src
** [[file:../my/twitter/twint.py][my.twitter.twint]]
** [[file:../src/my/twitter/twint.py][my.twitter.twint]]

Twitter data (tweets and favorites).

Expand All @@ -316,15 +316,15 @@ for cls, p in modules:
class twint:
export_path: Paths # path[s]/glob to the twint Sqlite database
#+end_src
** [[file:../my/twitter/archive.py][my.twitter.archive]]
** [[file:../src/my/twitter/archive.py][my.twitter.archive]]

Twitter data (uses [[https://help.twitter.com/en/managing-your-account/how-to-download-your-twitter-archive][official twitter archive export]])

#+begin_src python
class twitter_archive:
export_path: Paths # path[s]/glob to the twitter archive takeout
#+end_src
** [[file:../my/lastfm][my.lastfm]]
** [[file:../src/my/lastfm.py][my.lastfm]]

Last.fm scrobbles

Expand All @@ -335,7 +335,7 @@ for cls, p in modules:
"""
export_path: Paths
#+end_src
** [[file:../my/polar.py][my.polar]]
** [[file:../src/my/polar.py][my.polar]]

[[https://github.com/burtonator/polar-bookshelf][Polar]] articles and highlights

Expand All @@ -347,7 +347,7 @@ for cls, p in modules:
polar_dir: PathIsh = Path('~/.polar').expanduser()
defensive: bool = True # pass False if you want it to fail faster on errors (useful for debugging)
#+end_src
** [[file:../my/instapaper.py][my.instapaper]]
** [[file:../src/my/instapaper.py][my.instapaper]]

[[https://www.instapaper.com][Instapaper]] bookmarks, highlights and annotations

Expand All @@ -359,15 +359,15 @@ for cls, p in modules:
# path[s]/glob to the exported JSON data
export_path : Paths
#+end_src
** [[file:../my/github/gdpr.py][my.github.gdpr]]
** [[file:../src/my/github/gdpr.py][my.github.gdpr]]

Github data (uses [[https://github.com/settings/admin][official GDPR export]])

#+begin_src python
class github:
gdpr_dir: PathIsh # path to unpacked GDPR archive
#+end_src
** [[file:../my/github/ghexport.py][my.github.ghexport]]
** [[file:../src/my/github/ghexport.py][my.github.ghexport]]

Github data: events, comments, etc. (API data)

Expand All @@ -383,7 +383,7 @@ for cls, p in modules:
# if omitted, will use /tmp
cache_dir: Optional[PathIsh] = None
#+end_src
** [[file:../my/kobo.py][my.kobo]]
** [[file:../src/my/kobo.py][my.kobo]]

[[https://uk.kobobooks.com/products/kobo-aura-one][Kobo]] e-ink reader: annotations and reading stats

Expand Down
4 changes: 2 additions & 2 deletions doc/QUERY.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ You select the one you want by clicking `1` or `2` on your keyboard. Otherwise,
hpi query my.coding.commits.repos
```

The corresponding `repos` function this queries is defined in [`my/coding/commits.py`](../my/coding/commits.py)
The corresponding `repos` function this queries is defined in [`my/coding/commits.py`](../src/my/coding/commits.py)

### Ordering/Filtering/Streaming

Expand Down Expand Up @@ -199,7 +199,7 @@ To preview, you can use something like [`qgis`](https://qgis.org/en/site/) or fo

## Python reference

The `hpi query` command is a CLI wrapper around the code in [`query.py`](../my/core/query.py) and [`query_range.py`](../my/core/query_range.py). The `select` function is the core of this, and `select_range` lets you specify dates, timedelta, start-end ranges, and other CLI-specific code.
The `hpi query` command is a CLI wrapper around the code in [`query.py`](../src/my/core/query.py) and [`query_range.py`](../src/my/core/query_range.py). The `select` function is the core of this, and `select_range` lets you specify dates, timedelta, start-end ranges, and other CLI-specific code.

`my.core.query.select`:

Expand Down
10 changes: 5 additions & 5 deletions doc/SETUP.org
Original file line number Diff line number Diff line change
Expand Up @@ -157,10 +157,10 @@ Since it's a Python package, generally it's very *flexible* and there are many w
To find out which attributes you need to specify:

- check in [[file:MODULES.org][MODULES]]
- check in [[file:../my/config.py][the default config stubs]]
- check in [[file:../src/my/config.py][the default config stubs]]
- if there is nothing there, the easiest is perhaps to skim through the module's code and search for =config.= uses.

For example, if you search for =config.= in [[file:../my/emfit/__init__.py][emfit module]], you'll see that it's using =export_path=, =tz=, =excluded_sids= and =cache_path=.
For example, if you search for =config.= in [[file:../src/my/emfit/__init__.py][emfit module]], you'll see that it's using =export_path=, =tz=, =excluded_sids= and =cache_path=.

- or you can just try running them and fill in the attributes Python complains about!

Expand Down Expand Up @@ -316,7 +316,7 @@ It's understandable from the app developer's perspective, but it makes things fr

# todo hmm what if I could share deserialization with Polar app?

Here comes the HPI [[file:../my/polar.py][polar module]]!
Here comes the HPI [[file:../src/my/polar.py][polar module]]!

: |πŸ’Ύ ~/.polar (raw JSON data) |
: ⇓⇓⇓
Expand Down Expand Up @@ -369,7 +369,7 @@ Reddit has a proper API, so in theory HPI could talk directly to Reddit and retr
It doesn't deal with all with the complexities of API interactions.
Instead, it relies on other tools to put *intermediate, raw data*, on your disk and then transforms this data into something nice.

As an example, for [[file:../my/reddit.py][Reddit]], HPI is relying on data fetched by [[https://github.com/karlicoss/rexport][rexport]] library. So the pipeline looks like:
As an example, for [[file:../src/my/reddit][Reddit]], HPI is relying on data fetched by [[https://github.com/karlicoss/rexport][rexport]] library. So the pipeline looks like:

: < 🌐 Reddit |
: ⇓⇓⇓
Expand Down Expand Up @@ -427,7 +427,7 @@ What we do next is:
: ⇓ ⇓⇓ ⇓
: < python interface> < python interface> < python interface>

For merging the data, we're using a tiny auxiliary module, =my.twitter.all= (It's just 20 lines of code, [[file:../my/twitter/all.py][check it out]]).
For merging the data, we're using a tiny auxiliary module, =my.twitter.all= (It's just 20 lines of code, [[file:../src/my/twitter/all.py][check it out]]).

Since you have two different sources of raw data, you need to specify two bits of config:
# todo link to modules thing?
Expand Down

0 comments on commit 4910c86

Please sign in to comment.