Merge pull request #84 from pycalendar/issue-36

WIP: Add documentation website

Author: niccokunzmann

.readthedocs.yml

@@ -0,0 +1,11 @@
+version: 2
+formats: all
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  commands:
+    - git fetch --tags
+    - pip install -r docs/requirements.txt
+    - pip install -e .
+    - sphinx-build docs/ $READTHEDOCS_OUTPUT/html/

docs/Makefile

@@ -0,0 +1,14 @@
+SPHINXBUILD = .venv/bin/sphinx-build
+DOCS_DIR    = .
+BUILDDIR    = _build
+
+.venv:
+	python -m venv .venv
+	.venv/bin/pip install -r requirements.txt
+	.venv/bin/pip install -e ..
+
+html: .venv
+	$(SPHINXBUILD) -W $(DOCS_DIR) $(BUILDDIR)/html
+
+clean:
+	rm -rf $(BUILDDIR) .venv

docs/conf.py

@@ -0,0 +1,26 @@
+import datetime
+import importlib.metadata
+
+project = "ics-query"
+this_year = datetime.date.today().year
+copyright = f"{this_year}, Nicco Kunzmann"
+release = version = importlib.metadata.version("ics-query")
+
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "myst_parser",
+]
+
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "github_url": "https://github.com/pycalendar/ics-query",
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/ics-query",
+            "icon": "fa-solid fa-download",
+            "type": "fontawesome",
+        },
+    ],
+}

docs/download.md

@@ -0,0 +1,44 @@
+# Download
+
+Pre-built binaries are available on the [Releases] page.
+No Python installation required.
+
+## Windows
+
+Download `ics-query.exe` from the [Releases] page and run it directly:
+
+```shell
+ics-query.exe --version
+```
+
+## Linux (x86_64)
+
+Download `ics-query-linux-x86_64` from the [Releases] page.
+Make it executable and run it:
+
+```shell
+chmod +x ics-query-linux-x86_64
+./ics-query-linux-x86_64 --version
+```
+
+To use it without the path prefix, move it somewhere on your PATH:
+
+```shell
+mv ics-query-linux-x86_64 ~/.local/bin/ics-query
+ics-query --version
+```
+
+## macOS
+
+macOS binaries are not provided.
+Use [Homebrew or pip](install.md) instead.
+
+## Verifying the download
+
+After downloading, check that the version matches the release you downloaded:
+
+```shell
+ics-query --version
+```
+
+[Releases]: https://github.com/pycalendar/ics-query/releases

docs/examples.md

@@ -0,0 +1,236 @@
+# Examples
+
+`ics-query` takes a command, a time argument, one or more calendar files, and an output.
+Pass `-` as the calendar to read from stdin. Pass `-` as the output to write to stdout.
+
+```shell
+ics-query at 2019-03-04 calendar.ics -
+```
+
+## Events at a specific time
+
+Use `at` to get all occurrences at a date, month, year, or precise time.
+
+Get everything happening on a specific day:
+
+```shell
+ics-query at 2019-03-04 calendar.ics -
+```
+
+Get everything happening this month:
+
+```shell
+ics-query at `date +%Y-%m` calendar.ics -
+```
+
+Get everything happening right now (to the second):
+
+```shell
+ics-query at `date +%Y%m%d%H%M%S` calendar.ics -
+```
+
+Accepted time formats for `at` and for the `START` argument of `between`:
+
+| Format | Description |
+| ------ | ----------- |
+| `2019` | all of 2019 |
+| `2019-08` | August 2019 |
+| `2019-08-12` | 12 August 2019 |
+| `2019-08-12T17` | 17:00 to 18:00 on 12 August 2019 |
+| `2019-08-12T17:20` | 17:20 to 17:21 on 12 August 2019 |
+| `2019-08-12T17:20:00` | exactly 17:20:00 on 12 August 2019 |
+
+Compact formats without separators are also accepted: `20190812`, `20190812T1720`, `201908121720`.
+
+## Events within a time span
+
+Use `between` to get occurrences between a start and an end.
+Start is inclusive, end is exclusive.
+
+Get events in the next 7 days:
+
+```shell
+ics-query between `date +%Y%m%d` +7d calendar.ics -
+```
+
+Get events between two specific dates:
+
+```shell
+ics-query between 2024-05-01 2024-06-10 calendar.ics events.ics
+```
+
+Get events around New Year's Eve midnight:
+
+```shell
+ics-query between 2025-12-31T21:00 +6h calendar.ics -
+```
+
+The `END` argument can be a relative duration after `START`:
+
+| Duration | Description |
+| -------- | ----------- |
+| `+1d` | one day |
+| `+1h` | one hour |
+| `+1m` | one minute |
+| `+1s` | one second |
+| `+3600s` | one hour as seconds |
+| `+5d10h` | five days and 10 hours |
+
+The `+` prefix is optional.
+
+## First occurrence
+
+Use `first` to get only the first occurrence in each calendar file.
+
+```shell
+ics-query first calendar.ics -
+```
+
+## All occurrences
+
+Use `all` to get every occurrence in a calendar.
+
+```shell
+ics-query all calendar.ics -
+```
+
+Calendars with recurring events can produce a very large number of occurrences.
+Use `head` to limit the output:
+
+```shell
+ics-query all calendar.ics - | head -100
+```
+
+## Filtering by component type
+
+By default, `ics-query` returns `VEVENT`, `VTODO`, and `VJOURNAL` components.
+Use `-c` or `--component` to filter.
+
+Only events:
+
+```shell
+ics-query at 2024-08 -c VEVENT calendar.ics -
+```
+
+Only to-dos:
+
+```shell
+ics-query at 2024-08 -c VTODO calendar.ics -
+```
+
+Only journal entries:
+
+```shell
+ics-query at 2024-08 -c VJOURNAL calendar.ics -
+```
+
+Pass `-c` multiple times to include more than one type:
+
+```shell
+ics-query at 2024-08 -c VEVENT -c VTODO calendar.ics -
+```
+
+You can also set the component via environment variable:
+
+```shell
+export ICS_QUERY_COMPONENT=VEVENT
+ics-query at 2024-08 calendar.ics -
+```
+
+## Querying alarms
+
+Use `-c VALARM` to query components by their alarm times.
+`VALARM` is not included in the default output.
+
+Alarms behave differently from other components:
+
+- The parent component (`VEVENT`, `VTODO`) may fall outside the queried time span
+  while the alarm falls within it, and it will still be included.
+- Absolute alarms may appear only once, not for every recurrence.
+- Each result contains only one alarm.
+- Do not mix `-c VALARM` with other types. You will not be able to tell whether
+  the alarm or the parent component matched the time span.
+
+Get all alarms and show their trigger time and event summary:
+
+```shell
+ics-query all -c VALARM calendar.ics - | grep -E 'TRIGGER|SUMMARY'
+```
+
+## Timezones
+
+By default, `ics-query` uses each component's own timezone.
+Two events at 6am in different timezones both appear when you query by date,
+even though they are hours apart in absolute time.
+
+Use `--tz` to query in a specific timezone:
+
+```shell
+ics-query at --tz=Europe/Berlin 2024-08-20 calendar.ics -
+```
+
+Use `--tz=localtime` to query in your local system timezone:
+
+```shell
+ics-query at --tz=localtime 2024-08-20 calendar.ics -
+```
+
+Use `--tz=UTC` for UTC:
+
+```shell
+ics-query at --tz=UTC 2024-08-20 calendar.ics -
+```
+
+Set the timezone via environment variable:
+
+```shell
+export ICS_QUERY_TZ=Europe/Berlin
+ics-query at 2024-08-20 calendar.ics -
+```
+
+List all available timezone names:
+
+```shell
+ics-query --available-timezones
+```
+
+## Valid ICS output
+
+By default, the output contains only the matched components with no `VCALENDAR` wrapper
+and no `VTIMEZONE`. This is intentional for piping into other tools.
+
+To produce a valid `.ics` file that calendar applications can open, use `--as-calendar`:
+
+```shell
+ics-query at --as-calendar 2014-05-03 calendar.ics output.ics
+```
+
+The output is wrapped in a `VCALENDAR` block and includes any `VTIMEZONE` components
+from the source calendar.
+
+You can also set this via environment variable:
+
+```shell
+export ICS_QUERY_AS_CALENDAR=1
+ics-query at 2014-05-03 calendar.ics output.ics
+```
+
+## Multiple calendars
+
+Pass multiple files directly:
+
+```shell
+ics-query at 2024-08 calendar1.ics calendar2.ics -
+```
+
+Or concatenate them through stdin:
+
+```shell
+cat calendar1.ics calendar2.ics | ics-query at 2024-08 - -
+```
+
+## Fetching a calendar from the web
+
+```shell
+wget -qO- 'https://example.com/calendar.ics' | ics-query at 2024-08 - -
+```

docs/index.md

@@ -0,0 +1,13 @@
+# ics-query
+
+Find out what happens in ICS calendar files - query and filter RFC 5545 compatible `.ics` files for events, journals, TODOs and more.
+
+```{toctree}
+:maxdepth: 1
+
+overview
+install
+download
+examples
+maintenance
+```