Add advanced example, development, and contributing docs

README.md

@@ -9,10 +9,16 @@ It allows you to **infer** the full set of plausible time zones for the data, or
 
 ## Installation
 
-TODO - after pushing v0.1.0 to PyPI
+`tz-canary` is available on PyPI, so you can install it just like any other Python package:
+
+```bash
+pip install tz-canary
+```
 
 ## Usage
 
+### Time zone validation
+
 The simplest way to use `tz-canary` is to validate a given time zone for a time series:
 
 ```python
@@ -26,6 +32,8 @@ validate_time_zone(df.index, "America/New_York")  # will raise ImplausibleTimeZo
 validate_time_zone(df.index, "UTC")  # will raise ImplausibleTimeZoneError
 ```
 
+### Time zone inference
+
 You can also get a list of all plausible time zones for a time series:
 
 ```python
@@ -47,12 +55,64 @@ pprint(plausible_time_zones)
 #  zoneinfo.ZoneInfo(key='Europe/Zurich')}
 ```
 
-TODO - add example for building a `TransitionsData` object and using that to validate/infer many time series.
+### Advanced usage: inference with cached `TransitionsData`
+
+When processing many time series, it can be useful to cache the transitions data used by `tz-canary` to infer time zones.
+You can do this by creating a `TransitionsData` object and passing it to `infer_time_zone` (and this also works for `validate_time_zone`):
+
+```python
+import pandas as pd
+
+from tz_canary import TransitionsData, infer_time_zone
+
+# We create a TransitionsData object to avoid having to recompute the transitions for
+#   every call to validate_time_zone.
+transition_data = TransitionsData(2010, 2023)
+
+for i in range(10):
+    df = pd.read_csv(
+        "docs/data/example_data.csv",  # In reality, these would be different files
+        index_col="datetime",
+        parse_dates=True,
+    )
+    plausible_time_zones = infer_time_zone(df.index, transition_data=transition_data)
+    print(i, plausible_time_zones)
+```
 
 ## Development
 
-TODO - add overview of setup (git LFS, poetry, pre-commit, pytest, etc.)
+1. Make sure you have [git](https://git-scm.com/), [git LFS](https://git-lfs.com/), and [Poetry](https://python-poetry.org/) installed.
+2. Clone this repository:
+    ```bash
+    git clone https://github.com/leonoverweel/tz-canary
+    cd tz-canary
+    ```
+3. Install the development requirements:
+    ```bash
+    poetry install --with dev
+    ```
+4. Install the pre-commit hooks (used for linting):
+    ```bash
+    pre-commit install
+    ```
+5. Run the tests:
+    ```bash
+    poetry run pytest
+    ```
+
+### Making a release
+
+1. Bump the version number in `pyproject.toml` and commit the change.
+2. Make a [new release](https://github.com/leonoverweel/tz-canary/releases) on GitHub.
+3. Build the package:
+    ```bash
+    poetry build
+    ```
+4. Publish the package to PyPI:
+    ```bash
+    poetry publish
+    ```
 
 ## Contributing
 
-TODO - add contributing guidelines
+Please don't hesitate to open issues and PRs!

docs/examples/example_many.py

@@ -0,0 +1,16 @@
+import pandas as pd
+
+from tz_canary import TransitionsData, infer_time_zone
+
+# We create a TransitionsData object to avoid having to recompute the transitions for
+#   every call to validate_time_zone.
+transition_data = TransitionsData(2010, 2023)
+
+for i in range(10):
+    df = pd.read_csv(
+        "docs/data/example_data.csv",  # In reality, these would be different files
+        index_col="datetime",
+        parse_dates=True,
+    )
+    plausible_time_zones = infer_time_zone(df.index, transition_data=transition_data)
+    print(i, plausible_time_zones)

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tz-canary"
-version = "0.1.0"
+version = "0.1.1"
 description = "Infer plausible time zones for a time series dataset based on Daylight Savings Time switches"
 authors = ["Leon Overweel <l.overweel@gmail.com>"]
 readme = "README.md"