Repository navigation
docs: generate the SDK reference as Markdown with Dokka - #939
Conversation
Adds Dokka's GFM output as a build-time Gradle init script (not a project dependency, so nothing ships to SDK users), a script that groups its files by sdk-specs capability, and a release step that regenerates references/. Tags the public API with posthog-capability KDoc lines and adds short docs to a few public types that had none. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 047e8ab: 1 Must fix.
This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.
See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.
posthog-android Compliance ReportDate: 2026-11-09 18:40:19 UTC ✅ All Tests Passed!46/46 tests passed Capture Tests✅ 29/29 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
The modules already apply Dokka, so dokkaHtml needs no init script. BeautifulSoup reads each symbol page's signature, parameters and description, and markdownify turns the description into Markdown. Both are pinned in a docs-only requirements file, and the script has no regex. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Escaping now touches prose only, so code blocks show { and } as written.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The posthog-capability lines showed up in Android Studio's hover help for every SDK user. The generator now reads the capability for each entry label from docs/capabilities.json and the KDoc reads as it does on main. A PostHog member that is neither mapped nor listed in utils, an unknown slug, or a map entry with no member on the declared major fails the run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Skip @PostHogInternal members by their signature: the annotation is now @MustBeDocumented, so Dokka prints it. Drops the hard-coded name list. - Drop Dokka's copy button text, keep line breaks and the kotlin tag in samples. - Leave the core PostHog.setup and PostHog.with off the page; apps call PostHogAndroid's. - Map optOut to opt-in, and startSession, endSession and getDeviceId like iOS. - Don't let reference generation fail a release; set up Python and stage references/ for the commit. - Run on Python 3.9 with from __future__ import annotations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The release's reference step is best-effort, so a failure never blocks a release. generate-references.yml reruns it from main on demand and commits references/ when anything changed. Same shape as posthog-js's generate-references.yml. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reference step is best-effort, so a failure leaves the release green. A ::warning:: annotation now says so and points to generate-references.yml. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… event Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PR overviewNo security issues were found in this pull request. Reviews
|
| for module in MODULES: | ||
| for pkg in sorted(html_root(module).glob("com.posthog*")): | ||
| if ".internal" not in pkg.name and ".vendor" not in pkg.name: | ||
| pages.update({title(p): p for p in pkg.glob("-*/index.html")}) |
There was a problem hiding this comment.
P2 · Include nested types and companion APIs in the reference
For public nested declarations, this glob only discovers top-level types, and type_entry() never visits their children. The generated reference omits all SurveyQuestionBranching variants and companion APIs such as PostHogLogSeverity.from, despite using from in an example. Traverse nested public types and include companion members under their owning type.
| - name: 'Set up Python' | ||
| uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 | ||
| with: | ||
| python-version: '3.13' |
There was a problem hiding this comment.
P2 · Include documentation setup in the best-effort failure boundary
When setup-java or setup-python fails to download its runtime, the version-bump job stops before committing the version changes. Only the regeneration step has continue-on-error, so these new documentation prerequisites still block releases despite the best-effort requirement. Include both setup steps in the failure boundary and warn when either fails.
💡 Motivation and Context
We have a wave of breaking changes with new major versions for most SDKs. References are now read mostly by bots, not humans, and the HogRef format is heavy. Strapi then syncs
references/daily, and posthog.com builds the pages (PostHog/squeak-strapi#260, PostHog/posthog.com#21971).dokkaHtmlruns with no build changes. BeautifulSoup reads each symbol page's signature, parameters and description, and markdownify turns the description into Markdown (both pinned inbin/docs_scripts/requirements.txt, docs only). The script groups symbols by capability, fromdocs/capabilities.json, with no regex.docs/capabilities.jsonmaps each symbol to its sdk-specs capability, so the doc comments stay as they are. Generation fails on a stale entry, an unknown capability, or an unmapped client method.docs/getting-started.mdand a release step..github/workflows/generate-references.ymlreruns it by hand frommainand commitsreferences/when anything changed. It follows the prior art in posthog-js'sgenerate-references.yml, and it's the same in every SDK repo apart from the generation step.💚 How did you test it?
📝 Checklist
🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Claude Code: Sonnet 5.5 built it and Opus 5.5 opened it, directed by Vincent. Not yet reviewed line by line.
Merge order
🤖 Generated with Claude Code