Skip to content

Commit dc4783f

Browse files
Merge pull request #86 from pycalendar/issue-36-expand
Expand documentation website
2 parents 3146a9c + 1f7a72b commit dc4783f

10 files changed

Lines changed: 356 additions & 93 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Changelog
2+
3+
We automatically release versions that only update dependencies.
4+
If the version you installed does not show up here, only the dependencies have been updated.
5+
6+
- v0.5.12
7+
8+
- Expand documentation with command reference, glossary, changelog, and timezone pages. Extract changelog into `CHANGELOG.md`. See [Issue 36](https://github.com/pycalendar/ics-query/issues/36).
9+
10+
- v0.5.11
11+
12+
- Add documentation website at [ics-query.readthedocs.io](https://ics-query.readthedocs.io). See [Issue 36](https://github.com/pycalendar/ics-query/issues/36).
13+
14+
- v0.5.8
15+
16+
- Name Linux binary by platform and architecture (e.g. `ics-query-linux-x86_64`). See [Issue 70](https://github.com/pycalendar/ics-query/issues/70).
17+
18+
- v0.5.0
19+
20+
- Remove Python 3.9 support.
21+
22+
- v0.4.54
23+
24+
- Test and support Python 3.13 and 3.14. See [Issue 9](https://github.com/niccokunzmann/ics-query/issues/9).
25+
26+
- v0.4.36
27+
28+
- Test and document `VALARM`. See [Issue 16](https://github.com/niccokunzmann/ics-query/issues/16).
29+
30+
- v0.4.33
31+
32+
- Add `--as-calendar` parameter.
33+
34+
- v0.4.32
35+
36+
- Update dependencies.
37+
- Include recurrence ID in events to identify the occurrence in a series.
38+
- Update help message in command line.
39+
40+
- v0.4.1
41+
42+
- Automatic release with patch level version number increased.
43+
- Increase patch version instead of minor version for automatic releases.
44+
45+
- v0.3.4
46+
47+
- Update dependencies.
48+
- Start automatic release of dependencies increasing the version number.
49+
50+
- v0.3.3b
51+
52+
- Update dependencies.
53+
54+
- v0.3.2b
55+
56+
- Fix `--tz localtime` using `localtime` as timezone name instead of the local timezone name.
57+
- Fix tests on Windows.
58+
- Add Windows .exe build artifact.
59+
60+
- v0.3.1b
61+
62+
- Add `--license` option.
63+
64+
- v0.3.0b
65+
66+
- Add `--tz` timezone parameter.
67+
- Add `ics-query all` to get all occurrences.
68+
69+
- v0.2.1a
70+
71+
- Add `--component` to filter component types VEVENT, VJOURNAL and VTODO.
72+
73+
- v0.2.0a
74+
75+
- Add `ics-query first <calendar> <output>` for earliest occurrences.
76+
- Add `ics-query between <span_start> <span_stop> <calendar> <output>` to query time ranges.
77+
78+
- v0.1.1a
79+
80+
- Add `--version`.
81+
- Add `ics-query at <date> <calendar> <output>`.
82+
- Add support for multiple calendars in one input.
83+
84+
- v0.1.0a
85+
86+
- Update Python version compatibility.
87+
- Add development documentation.
88+
89+
- v0.0.1a
90+
91+
- First version.

‎README.md‎

Lines changed: 10 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -464,109 +464,29 @@ PATCH version number.
464464
To release a new version with a new MINOR or MAJOR version number change,
465465
follow these steps:
466466

467-
1. edit the Changelog Section
468-
2. create a commit and push it
469-
3. wait for [GitHub Actions] to finish the build
470-
4. create a tag and push it
467+
1. Edit `CHANGELOG.md`.
468+
2. Create a commit and push it.
469+
3. Wait for [GitHub Actions](https://github.com/pycalendar/ics-query/actions) to finish.
470+
4. Create a tag and push it:
471471

472472
```shell
473-
git tag v0.1.0
474-
git push origin v0.1.0
473+
git tag v0.2.0
474+
git push origin v0.2.0
475475
```
476476

477-
5. Notify the issues about their release
477+
5. Notify the issues about their release.
478478

479479
To add a new Python version, update these files:
480480

481481
- `tox.ini` - add the version to `envlist`
482482
- `pyproject.toml` - add a classifier
483483
- `.github/workflows/tests.yml` - add the version to the `run-tests` and `test-version` matrices
484-
- `README.md` - add a changelog entry
484+
- `.readthedocs.yml` - update the Python version if needed
485+
- `CHANGELOG.md` - add a changelog entry
485486

486487
## Changelog
487488

488-
We automatically release the versions that only update dependencies.
489-
If the version you installed does not show up here, only the dependencies
490-
have been updated.
491-
492-
- v0.5.8
493-
494-
- Name Linux binary by platform and architecture (e.g. `ics-query-linux-x86_64`). See [Issue 70](https://github.com/pycalendar/ics-query/issues/70).
495-
496-
- v0.5.0
497-
498-
- Remove Python 3.9 support.
499-
500-
- v0.4.54
501-
502-
- Test and support Python 3.13 and 3.14. See [Issue 9](https://github.com/niccokunzmann/ics-query/issues/9).
503-
504-
- v0.4.36
505-
506-
- Test and document `VALARM`. See [Issue 16](https://github.com/niccokunzmann/ics-query/issues/16).
507-
508-
- v0.4.33
509-
510-
- Add `--as-calendar` parameter.
511-
512-
- v0.4.32
513-
514-
- Update dependencies.
515-
- Include recurrence ID in events to identify the occurrence in a series.
516-
- Update help message in command line.
517-
518-
- v0.4.1
519-
520-
- Automatic release with patch level version number increased
521-
- Increase patch version instead of minor version for automatic releases
522-
523-
- v0.3.4
524-
525-
- Update dependencies
526-
- Start automatic release of dependencies increasing the version number
527-
528-
- v0.3.3b
529-
530-
- Update dependencies
531-
532-
- v0.3.2b
533-
534-
- Fix that `--tz localtime` would use `localtime` as timezone name instead of the local timezone name.
535-
- Fix tests on Windows
536-
- Add Windows .exe build artifact
537-
538-
- v0.3.1b
539-
540-
- Add `--license` option
541-
542-
- v0.3.0b
543-
544-
- Add `--tz` timezone parameter
545-
- Add `ics-query all` to get all occurrences
546-
547-
- v0.2.1a
548-
549-
- Add `--component` to filter component types VEVENT, VJOURNAL and VTODO
550-
551-
- v0.2.0a
552-
553-
- Add `ics-query first <calendar> <output>` for earliest occurrences
554-
- Add `ics-query between <span_start> <span_stop> <calendar> <output>` to query time ranges
555-
556-
- v0.1.1a
557-
558-
- Add `--version`
559-
- Add `ics-query at <date> <calendar> <output>`
560-
- Add support for multiple calendars in one input
561-
562-
- v0.1.0a
563-
564-
- Update Python version compatibility
565-
- Add development documentation
566-
567-
- v0.0.1a
568-
569-
- first version
489+
See [CHANGELOG.md](CHANGELOG.md).
570490

571491
## Related Work
572492

‎docs/changelog.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
```{include} ../CHANGELOG.md
2+
```

‎docs/conf.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,12 @@
99
extensions = [
1010
"sphinx.ext.intersphinx",
1111
"sphinx_copybutton",
12+
"sphinx_design",
1213
"myst_parser",
1314
]
1415

16+
myst_enable_extensions = ["colon_fence"]
17+
1518
html_theme = "pydata_sphinx_theme"
1619
html_theme_options = {
1720
"github_url": "https://github.com/pycalendar/ics-query",

‎docs/glossary.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Glossary
2+
3+
```{glossary}
4+
ICS file
5+
A text file in the iCalendar format with a `.ics` extension. Defined by RFC 5545.
6+
7+
RFC 5545
8+
The Internet standard that defines the iCalendar format. Specifies the structure of `.ics` files, component types, properties, and recurrence rules.
9+
10+
VCALENDAR
11+
The top-level wrapper component in an `.ics` file. Contains all other components.
12+
13+
VEVENT
14+
A calendar event. Has a start time (`DTSTART`), optional end time (`DTEND`), and optional recurrence rules.
15+
16+
VTODO
17+
A to-do item. Like a `VEVENT` but represents a task rather than a scheduled event. May have a due date instead of an end time.
18+
19+
VJOURNAL
20+
A journal entry. Represents a note or record associated with a date.
21+
22+
VALARM
23+
An alarm attached to a `VEVENT` or `VTODO`. Has a trigger time (absolute or relative to the parent component). Not included in default output — use `-c VALARM` to query alarms.
24+
25+
VTIMEZONE
26+
A timezone definition embedded in a calendar file. Defines the UTC offset and daylight saving rules for a named timezone.
27+
28+
DTSTART
29+
The start date or date-time of a component. For recurring components, this is the start of the first occurrence.
30+
31+
DTEND
32+
The end date or date-time of a component. Exclusive — an event ending at 10:00 does not overlap a query starting at 10:00.
33+
34+
RRULE
35+
A recurrence rule. Defines how a component repeats — daily, weekly, monthly, and so on. `ics-query` expands these into individual occurrences automatically.
36+
37+
EXDATE
38+
A list of dates excluded from a recurrence series. Occurrences on these dates are skipped.
39+
40+
occurrence
41+
A single instance of a component. A weekly recurring event has one occurrence per week. `ics-query` filters and returns occurrences, not the raw recurring rule.
42+
43+
recurrence
44+
A component that repeats over time, defined by an `RRULE`. `ics-query` uses [recurring-ical-events] to expand recurrences into individual occurrences.
45+
46+
floating time
47+
A date-time with no timezone. Interpreted as local time wherever it is read. Contrast with a timezone-aware date-time which has a fixed `TZID`.
48+
49+
X-WR-TIMEZONE
50+
A non-standard calendar property used by some applications (e.g., Google Calendar exports) to specify a calendar-wide timezone. `ics-query` handles this automatically.
51+
```
52+
53+
[recurring-ical-events]: https://pypi.org/project/recurring-ical-events/

‎docs/index.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,47 @@
11
# ics-query
22

3-
Find out what happens in ICS calendar files - query and filter RFC 5545 compatible `.ics` files for events, journals, TODOs and more.
3+
Query and filter RFC 5545 compatible `.ics` calendar files from the command line.
4+
5+
::::{grid} 1 1 2 2
6+
:gutter: 3
7+
8+
:::{grid-item-card} Get started
9+
:link: install
10+
:link-type: doc
11+
Install via pip, pipx, or Homebrew. Or download a pre-built binary.
12+
:::
13+
14+
:::{grid-item-card} Examples
15+
:link: examples
16+
:link-type: doc
17+
Query events by date, filter by component type, work with timezones, and pipe output to other tools.
18+
:::
19+
20+
:::{grid-item-card} Command reference
21+
:link: reference
22+
:link-type: doc
23+
Every command, flag, and environment variable in one place.
24+
:::
25+
26+
:::{grid-item-card} Timezones
27+
:link: timezones
28+
:link-type: doc
29+
How timezone handling works and when to use `--tz`.
30+
:::
31+
32+
::::
433

534
```{toctree}
635
:maxdepth: 1
36+
:hidden:
737
838
overview
939
install
1040
download
1141
examples
42+
reference
43+
timezones
44+
glossary
45+
changelog
1246
maintenance
1347
```

‎docs/maintenance.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Each commit to `main` is automatically published with an increased patch version
9696

9797
To release a new minor or major version:
9898

99-
1. Edit the changelog section in `README.md`.
99+
1. Edit `CHANGELOG.md`.
100100
2. Create a commit and push it.
101101
3. Wait for [GitHub Actions](https://github.com/pycalendar/ics-query/actions) to finish.
102102
4. Create a tag and push it:
@@ -115,4 +115,5 @@ When a new Python version is released, update these files:
115115
- `tox.ini` — add the version to `envlist`
116116
- `pyproject.toml` — add a `Programming Language :: Python :: X.Y` classifier
117117
- `.github/workflows/tests.yml` — add the version to both the `run-tests` and `test-version` matrices
118-
- `README.md` — add a changelog entry
118+
- `.readthedocs.yml` — update the Python version if needed
119+
- `CHANGELOG.md` — add a changelog entry

0 commit comments

Comments
 (0)