Skip to content

Commit df5408d

Browse files
niccokunzmannniccokunzmann
committed
Document advanced usage
1 parent d98666b commit df5408d

File tree

6 files changed

+228
-50
lines changed

6 files changed

+228
-50
lines changed

‎docs/advanced.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
icon: material/book-open-blank-variant-outline
3+
---
4+
5+
Advanced Usage
6+
==============
7+
8+
This document provides a guide to advanced usage of the `ical2jcal` project.
9+
10+
Convert an online calendar to JSON
11+
----------------------------------
12+
13+
Calendar services line Nextcloud, Google Calendar and Microsoft Outlook can provide an link to a `.ics` file for your calendar.
14+
15+
In the example below, we convert the example calender from our project website to JSON.
16+
17+
=== "curl[^1]"
18+
19+
```bash
20+
curl -sL https://github.com/niccokunzmann/ical2jcal/raw/refs/heads/main/example.ics | ical2jcal --pretty
21+
```
22+
23+
```json
24+
[
25+
"vcalendar",
26+
[
27+
[
28+
"version",
29+
{},
30+
"text",
31+
"2.0"
32+
],
33+
[
34+
"prodid",
35+
{},
36+
"text",
37+
"-//niccokunzmann//ical2jcal//EN"
38+
]
39+
],
40+
[]
41+
]
42+
```
43+
44+
=== "wget[^2]"
45+
46+
```bash
47+
$ wget -qO- https://github.com/niccokunzmann/ical2jcal/raw/refs/heads/main/example.ics | ical2jcal --pretty
48+
```
49+
50+
```json
51+
[
52+
"vcalendar",
53+
[
54+
[
55+
"version",
56+
{},
57+
"text",
58+
"2.0"
59+
],
60+
[
61+
"prodid",
62+
{},
63+
"text",
64+
"-//niccokunzmann//ical2jcal//EN"
65+
]
66+
],
67+
[]
68+
]
69+
```
70+
71+
Filter the JSON calendar with `jq`
72+
----------------------------------
73+
74+
Once converted, you can filter the JSON calendar using `jq`[^3].
75+
76+
In this example, we only print the `prodid` field of the calendar.
77+
78+
```bash
79+
$ ical2jcal example.ics | jq '.[1][] | select(.[0] == "prodid") | .[3]'
80+
```
81+
82+
Output:
83+
84+
```json
85+
"-//niccokunzmann//ical2jcal//EN"
86+
```
87+
88+
Here, we use `jq` to get all event summaries.
89+
90+
```bash
91+
$ ical2jcal other-example.ics | jq '.[2][] | select(.[0] == "vevent") | .[1][] | select(.[0] == "summary") | .[3]'
92+
```
93+
94+
Output:
95+
96+
```json
97+
"Planning meeting"
98+
```
99+
100+
Get today's events as JSON
101+
--------------------------
102+
103+
Given you have a calendar file as a valid jCalendar, you can use different tools to filter the calendar by date and time and use the JSON output.
104+
105+
=== "ics-query[^4]"
106+
107+
```bash
108+
jcal2ical input.jcal | ics-query at --as-calendar `` - - | ical2jcal --pretty
109+
```
110+
111+
Output:
112+
113+
```json
114+
[
115+
"vcalendar",
116+
[
117+
...
118+
],
119+
[
120+
...
121+
]
122+
]
123+
```
124+
125+
=== "icalendar-events-cli[^5]"
126+
127+
```bash
128+
$ jcal2ical my-calendar.jcal my-calendar.ics
129+
$ icalendar-events-cli \
130+
--calendar.url file://`pwd`/my-calendar.ics \
131+
--filter.start-date `date +%Y-%m-%d`T00:00:00 \
132+
--filter.end-date `date +%Y-%m-%d`T23:59:59
133+
```
134+
135+
Output:
136+
137+
```text
138+
Start Date: 2026-02-03T21:10:54+00:00
139+
End Date: 2026-02-03T23:59:59+00:00
140+
Number of Events: 0
141+
```
142+
143+
[^1]: [curl website](https://curl.se/)
144+
[^2]: [wget website](https://www.gnu.org/software/wget/)
145+
[^3]: [jq website](https://jqlang.org)
146+
[^4]: [ics-query website](https://pypi.org/project/ics-query/)
147+
[^5]: [icalendar-events-cli website](https://github.com/waldbaer/icalendar-events-cli)

‎docs/development.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
icon: material/tools
2+
---
3+
4+
Development Guide
5+
=================
6+
7+
This document provides a guide to developeing the `ical2jcal` project.
8+
9+
Setup `git`
10+
-----------
11+
12+
1. Install [git](https://git-scm.com/).
13+
2. Clone the repository:
14+
15+
```bash
16+
git clone https://github.com/niccokunzmann/ical2jcal.git
17+
cd ical2jcal
18+
```
19+
20+
Setup `uv`
21+
----------
22+
23+
Install [uv](https://docs.astral.sh/uv/getting-started/installation).
24+
To install uv, run:
25+
26+
=== "macOS and Linux"
27+
28+
```bash
29+
curl -LsSf https://astral.sh/uv/install.sh | sh
30+
```
31+
32+
=== "Windows"
33+
34+
```powershell
35+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
36+
```
37+
38+
Then install the `ical2jcal` package and its dependencies:
39+
40+
```bash
41+
uv sync
42+
```

‎docs/index.md‎

Lines changed: 33 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,64 @@
11
---
2-
icon: material/math-integral
2+
icon: material/calendar-expand-horizontal
33
status: new
44
---
55

6-
# `fact` User Guide
6+
# `ical2jcal` User Guide
77

8-
??? info "`python-blueprint` Project"
8+
This document enables you to convert iCalendar to jCalendar and vice versa, using the commands `ical2jcal` and `jcal2ical` on the command line.
99

10-
For more information on how this was built and deployed, as well as other Python best
11-
practices, see [`python-blueprint`](https://github.com/johnthagen/python-blueprint).
12-
13-
!!! info
14-
15-
This user guide is purely an illustrative example that shows off several features of
16-
[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and included Markdown
17-
extensions[^1].
10+
## Installation
1811

19-
[^1]: See `python-blueprint`'s `mkdocs.yml` for how to enable these features.
12+
`ical2jcal` is available on [PyPI](https://pypi.org/project/ical2jcal/).
13+
It is compatible with [Python 3.10](https://www.python.org/) and later.
2014

21-
## Installation
15+
You have several options to install this tool.
2216

23-
First, [install `uv`](https://docs.astral.sh/uv/getting-started/installation):
17+
=== "pip"
2418

25-
=== "macOS and Linux"
19+
`pip` comes with Python. To install this tool, run:
2620

2721
```bash
28-
curl -LsSf https://astral.sh/uv/install.sh | sh
22+
python -m pip install ical2jcal
2923
```
3024

31-
=== "Windows"
25+
=== "pipx"
3226

33-
```powershell
34-
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
27+
After you have installed [pipx](https://pipx.pypa.io/stable/installation/), run:
28+
29+
```bash
30+
pipx install ical2jcal
3531
```
3632

37-
Then install the `fact` package and its dependencies:
33+
=== "uv"
3834

39-
```bash
40-
uv sync
41-
```
35+
The [development guide](development.md) provides instructions on how to install `ical2jcal` using `uv`.
4236

43-
## Quick Start
37+
## Convert `.ics` to JSON
4438

45-
To run the included CLI:
39+
iCalendar files have the `.ics` extension.
40+
You can convert them to an [RFC 7265] compatible JSON using the `ical2jcal` command.
41+
We recommend using the `.jcal` extension for compatible JSON files.
42+
43+
The example below converts the `example.ics` file to `example.jcal`:
4644

4745
```bash
48-
uv run fact 3
46+
ical2jcal example.ics example.jcal
4947
```
5048

51-
To use `fact` as a library within your project, import the `factorial` function and execute the
52-
API like:
53-
54-
*[API]: Application Programming Interface
49+
For more options, view the [command line reference](ical2jcal.md).
5550

56-
```python
57-
from fact.lib import factorial
58-
59-
assert factorial(3) == 6 # (1)!
60-
```
51+
## Convert JSON to `.ics`
6152

62-
1. This assertion will be `True`
53+
[RFC 7265] compatible JSON files can be converted with the `jcal2ical` command.
6354

64-
!!! tip
55+
The example below converts the `example.jcal` file to `example.ics`:
6556

66-
Within PyCharm, use ++tab++ to auto-complete suggested imports while typing.
67-
68-
### Expected Results
57+
```bash
58+
jcal2ical example.jcal example.ics
59+
```
6960

70-
<div class="center-table" markdown>
61+
For more options, view the [command line reference](jcal2ical.md).
7162

72-
| Input | Output |
73-
|:-----:|:------:|
74-
| 1 | 1 |
75-
| 2 | 2 |
76-
| 3 | 6 |
77-
| 4 | 24 |
7863

79-
</div>
64+
[RFC 7265]: https://tools.ietf.org/html/rfc7265

‎docs/static/calendar-expand-horizontal.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/static/math-integral-box.png‎

-1.24 KB
Binary file not shown.

‎mkdocs.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,10 @@ theme:
1515
primary: green
1616
accent: yellow
1717
icon:
18-
logo: material/math-integral-box
18+
logo: material/calendar-expand-horizontal
1919
# GitHub specific.
2020
repo: fontawesome/brands/github
21-
favicon: static/math-integral-box.png
21+
favicon: static/calendar-expand-horizontal.svg
2222
features:
2323
- content.code.annotate
2424
- content.code.copy
@@ -92,10 +92,13 @@ repo_url: https://github.com/niccokunzmann/ical2jcal
9292
edit_uri: edit/main/docs/user_guide/docs/
9393
nav:
9494
- index.md
95+
- advanced.md
9596
- Command Line:
9697
- ical2jcal.md
9798
- jcal2ical.md
9899
- compatibility.md
100+
- Contributing:
101+
- development.md
99102
- Licensing:
100103
- licenses/license.md
101104
- licenses/license_report.md

0 commit comments

Comments
 (0)