Skip to content

docs: complete documentation for JSCalendar/jCal, auth, DNS rebinding fix, and encoding support - #169

Merged
SashankBhamidi merged 4 commits into
mainfrom
docs/feature-docs
Sep 15, 2026
Merged

SashankBhamidi merged 4 commits into
mainfrom
docs/feature-docs

Conversation

@SashankBhamidi

Copy link
Copy Markdown
Member

Docs for these four features were written alongside each merged PR (#162, #164, #165, #167), but never finished. This bundles them together with complete documentation for all four.

What's documented

  • JSCalendar and jCal anonymization (anonymize_jscal, anonymize_jcal), including a new API reference page
  • The DNS rebinding fix and /fetch's actual security model (SSRF rule, redirect limit)
  • Basic/Bearer auth for /fetch and Fernet links
  • Non-UTF-8 encoding support, the --encoding/--format CLI flags, and declared-charset handling

Also fixed while auditing

  • A wrong ATTENDEE/ORGANIZER example (the email was shown unchanged; it's hashed too)
  • An incomplete preserved-properties table (missing timezone/alarm/freebusy/relationship properties)
  • Imprecise exception message text in the Python API error-handling examples
  • A stale error case removed from /anonymized's docs
  • Fernet key validation requirements, and the Cloudflare Workers deployment architecture for contributors

Found a bug along the way: anonymize() crashes on a VTODO with COMPLETED or PERCENT-COMPLETE (#168). Not fixed here, docs describe current behavior.

Also in this PR

  • Restructured the docs around Diataxis (tutorials/how-to/reference/explanation)
  • Switched the change log to towncrier
  • Added a Code of Conduct and AI policy section, and an NLnet funding acknowledgment

@codecov

codecov Bot commented Sep 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@SashankBhamidi
SashankBhamidi merged commit 1076f46 into main Sep 15, 2026
15 checks passed
@SashankBhamidi
SashankBhamidi deleted the docs/feature-docs branch September 15, 2026 20:21
@SashankBhamidi

Copy link
Copy Markdown
Member Author

@stevepiercy heads up, this touches a lot of the docs you're reviewing for your NLnet milestone, so wanted to flag it before you get to it.

First commit (7dee062) is the actual new doc content for the four features (JSCalendar/jCal, the DNS rebinding fix, auth, encoding support). That's probably the one to look at closest since it's new.

Second commit (154a546) is a bunch of small fixes I found while auditing the existing docs, not related to those four features. Wanted to call out exactly where so you're not hunting for them. Linking to the final tree since the third commit moved a bunch of files around for the Diataxis restructure.

field_modes now takes AnonymizeMode members directly, not just strings:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L101

Preserved properties table was missing timezone, alarm, freebusy, and relationship properties, plus a note that ATTACH/URL/GEO get anonymized not preserved, and a flag for the COMPLETED/PERCENT COMPLETE bug in #168:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L179-L284

The ATTENDEE/ORGANIZER example was just wrong, it showed the email staying the same when it actually gets hashed too:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L339-L350

Exception message text now matches what anonymize() actually raises:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L515
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L526
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L537
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L551
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/python-api.rst#L557

config.rst didn't have a Usage section before, added one:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/reference/config.rst#L13

Gunicorn/uvloop detail, the FERNET_KEY length requirement, and a fix to the SSRF rule description:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/how-to/self-hosting.rst#L67
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/how-to/self-hosting.rst#L95
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/how-to/self-hosting.rst#L214

Frontend field sync and localStorage behavior, declared charset handling, and the redirect limit:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/how-to/web-service.rst#L109
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/how-to/web-service.rst#L213
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/how-to/web-service.rst#L323
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/how-to/web-service.rst#L377

New Cloudflare Workers deployment section for contributors:
https://github.com/pycalendar/icalendar-anonymizer/blob/eb5b7fa56ef2d2e858758487b4b6ecb5450ead05/docs/contribute.rst#L486

@SashankBhamidi SashankBhamidi mentioned this pull request Oct 6, 2026
2 of 6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants