Repository navigation
WIP: Add documentation website #84
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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", | ||
|
SashankBhamidi marked this conversation as resolved.
Resolved
|
||
| "icon_links": [ | ||
| { | ||
| "name": "PyPI", | ||
| "url": "https://pypi.org/project/ics-query", | ||
| "icon": "fa-solid fa-download", | ||
| "type": "fontawesome", | ||
| }, | ||
| ], | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
SashankBhamidi marked this conversation as resolved.
Resolved
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 - - | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.