how-to coverage, pycal theming, RFC citation audit

.github/workflows/tests.yml

@@ -65,6 +65,54 @@ jobs:
       - name: Check code format
         run: ruff format --check .
 
+  vale:
+    name: Check docs prose with Vale
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+
+      - name: Install docutils
+        run: pip install docutils==0.22.4
+
+      - name: Install Vale
+        run: |
+          curl -sL https://github.com/errata-ai/vale/releases/download/v3.24.0/vale_3.24.0_Linux_64-bit.tar.gz | tar -xz -C /usr/local/bin vale
+
+      - name: Sync Vale styles
+        run: vale sync
+
+      - name: Lint docs
+        run: vale --no-exit docs/
+
+  docs:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build docs
+        run: sphinx-build -W -b html docs docs/_build/html
+
   mypy:
     name: Type check with mypy
     runs-on: ubuntu-latest

.gitignore

@@ -36,6 +36,10 @@ htmlcov/
 .nox/
 .hypothesis/
 
+# Linting and type-checking caches
+.ruff_cache/
+.mypy_cache/
+
 # Virtual environments
 .venv
 venv/
@@ -61,5 +65,9 @@ src/calendaring_jmap/_version.py
 # uv lock file
 uv.lock
 
-# Docs build
-docs/_build/
+# Docs build (including comparison builds under other names, e.g. docs/_build2)
+docs/_build*/
+
+# Vale-synced third-party style packages (fetched by `vale sync`)
+docs/.vale/styles/Microsoft/
+docs/.vale/styles/signs-of-ai-writing/

.readthedocs.yml

@@ -1,15 +1,18 @@
 # SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
 version: 2
 
 build:
   os: ubuntu-24.04
   tools:
     python: "3.12"
+  jobs:
+    post_checkout:
+      # sphinx-last-updated-by-git needs full history; RTD's default clone
+      # is shallow (depth 50), so a file untouched longer than that would
+      # otherwise show no last-updated date.
+      - git fetch --unshallow || true
 
 sphinx:
   configuration: docs/conf.py

.vale.ini

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+StylesPath = docs/.vale/styles
+Vocab = Base
+MinAlertLevel = suggestion
+Packages = Microsoft, https://github.com/ammil-industries/vale-signs-of-ai-writing/releases/download/v0.1.1/signs-of-ai-writing.zip
+
+[*.rst]
+BasedOnStyles = Vale, Microsoft, signs-of-ai-writing, calendaring-jmap
+Vale.Terms = NO

README.md

@@ -45,7 +45,15 @@ Full documentation: https://calendaring-jmap.readthedocs.io/
 
 - [RFC 8620](https://www.rfc-editor.org/rfc/rfc8620): JMAP core
 - [draft-ietf-jmap-calendars](https://datatracker.ietf.org/doc/draft-ietf-jmap-calendars/): JMAP Calendars
-- [RFC 8984](https://www.rfc-editor.org/rfc/rfc8984): JSCalendar
+- [RFC 8984](https://www.rfc-editor.org/rfc/rfc8984): JSCalendar, the conversion target for iCalendar
+- [draft-ietf-calext-jscalendar-icalendar](https://datatracker.ietf.org/doc/draft-ietf-calext-jscalendar-icalendar/): iCalendar and JSCalendar conversion rules
+- [RFC 9610](https://www.rfc-editor.org/rfc/rfc9610): JMAP Contacts
+- [RFC 9670](https://www.rfc-editor.org/rfc/rfc9670): JMAP Sharing and Principals
+- [draft-ietf-jmap-tasks](https://datatracker.ietf.org/doc/draft-ietf-jmap-tasks/): JMAP Tasks (expired; see the [server compatibility](https://calendaring-jmap.readthedocs.io/en/stable/reference/server-compatibility.html) page, no known server implements it yet)
+
+## Changelog
+
+See the [change log](https://calendaring-jmap.readthedocs.io/en/stable/changelog.html).
 
 ## Contributing
 

REUSE.toml

@@ -17,6 +17,12 @@ precedence = "override"
 SPDX-FileCopyrightText = "2026 calendaring-jmap contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
 
+[[annotations]]
+path = "docs/.vale/styles/config/vocabularies/Base/accept.txt"
+precedence = "override"
+SPDX-FileCopyrightText = "2026 calendaring-jmap contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
 # PEP 561 marker file, must be empty
 [[annotations]]
 path = "src/calendaring_jmap/py.typed"
@@ -25,7 +31,7 @@ SPDX-FileCopyrightText = "2026 calendaring-jmap contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
 
 # Towncrier news fragments. short-lived, deleted once folded into
-# CHANGES.rst at release time. Not worth a header each.
+# docs/changelog.rst at release time. Not worth a header each.
 [[annotations]]
 path = "news/*"
 precedence = "override"
@@ -46,3 +52,11 @@ path = ".github/ISSUE_TEMPLATE/*.md"
 precedence = "override"
 SPDX-FileCopyrightText = "2026 calendaring-jmap contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+# pycal.org's logo, reused here to show this project is part of the
+# Python Calendaring Ecosystem. Binary PNG, no header possible.
+[[annotations]]
+path = "docs/_static/img/pycal-icon.png"
+precedence = "override"
+SPDX-FileCopyrightText = "2026 pycal.org"
+SPDX-License-Identifier = "CC-BY-SA-4.0"

docs/.vale/styles/calendaring-jmap/FrustrationWords.yml

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+extends: existence
+message: "'%s' can read as condescending to a reader who can't complete the task as described; see the contributor guide's prose-style section."
+link: https://docs.pylonsproject.org/projects/docs-style-guide/
+ignorecase: true
+level: warning
+tokens:
+  - simple
+  - simply
+  - just
+  - very
+  - easy
+  - easily

docs/.vale/styles/calendaring-jmap/Terms.yml

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+extends: substitution
+message: "Prefer '%s' over '%s'."
+link: https://docs.pylonsproject.org/projects/docs-style-guide/
+level: warning
+ignorecase: false
+swap:
+  Github: GitHub
+  GITHUB: GitHub
+  addon: add-on
+  addons: add-ons
+  plugin: plug-in
+  plugins: plug-ins

docs/.vale/styles/config/vocabularies/Base/accept.txt

@@ -0,0 +1,41 @@
+AGPL
+ASCII
+async
+autodoc
+calendaring-jmap
+calendaring_jmap
+config
+coroutines?
+CRUD
+Diataxis
+dicts
+docstrings?
+else's
+filename
+fixup
+hardcoding
+iCalendar
+IETF
+inlined
+JMAP
+JSCalendar
+niquests
+NNNN
+parens
+pytest
+repo
+RFC
+RFCs
+RST
+sharees?
+snake_case
+subclassing
+substrings?
+TLS
+UID
+unobfuscated
+[Uu]ntrusted
+URN
+VCALENDAR
+VCONFERENCE
+VEVENTs?