Skip to content

docs: generate the SDK reference as Markdown with Dokka - #939

Merged
gewenyu99 merged 8 commits into
mainfrom
markdown-reference-adapter
Nov 11, 2026
Merged

gewenyu99 merged 8 commits into
mainfrom
markdown-reference-adapter

Conversation

@gewenyu99

@gewenyu99 gewenyu99 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

💡 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).

  • The modules already apply Dokka, so dokkaHtml runs with no build changes. BeautifulSoup reads each symbol page's signature, parameters and description, and markdownify turns the description into Markdown (both pinned in bin/docs_scripts/requirements.txt, docs only). The script groups symbols by capability, from docs/capabilities.json, with no regex.
  • docs/capabilities.json maps 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.
  • Adds a few missing field docs, docs/getting-started.md and a release step.
  • The release's reference step is best-effort, so a failure never blocks a release. .github/workflows/generate-references.yml reruns it by hand from main and commits references/ when anything changed. It follows the prior art in posthog-js's generate-references.yml, and it's the same in every SDK repo apart from the generation step.

💚 How did you test it?

  • Regenerating reproduces the pages in the next PR, with JDK 17 locally. The release step hasn't run in CI.

📝 Checklist

  • All commits are signed
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

🤖 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

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>
@gewenyu99 gewenyu99 self-assigned this Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor
⚠️ `posthog` is modified but this PR has no changeset

This is informational — the PR is not blocked. Click the triangle above to collapse, or push a fix and this comment will auto-delete.

Modified in this PR but no changeset added:

  • posthog

If this change should ship, run pnpm changeset and select a bump level.
If it isn't user-facing (refactor with no behavior change, internal tooling, generated files), no action needed.

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread bin/docs_scripts/generate_markdown.py Resolved
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

posthog-android Compliance Report

Date: 2026-11-09 18:40:19 UTC
Duration: 118409ms

✅ All Tests Passed!

46/46 tests passed


Capture Tests

✅ 29/29 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 346ms
Format Validation.Event Has Uuid ✅ 28ms
Format Validation.Event Has Lib Properties ✅ 27ms
Format Validation.Distinct Id Is String ✅ 25ms
Format Validation.Token Is Present ✅ 27ms
Format Validation.Custom Properties Preserved ✅ 29ms
Format Validation.Event Has Timestamp ✅ 25ms
Retry Behavior.Retries On 503 ✅ 7027ms
Retry Behavior.Does Not Retry On 400 ✅ 4024ms
Retry Behavior.Does Not Retry On 401 ✅ 4028ms
Retry Behavior.Respects Retry After Header ✅ 7026ms
Retry Behavior.Implements Backoff ✅ 17034ms
Retry Behavior.Retries On 500 ✅ 7019ms
Retry Behavior.Retries On 502 ✅ 7018ms
Retry Behavior.Retries On 504 ✅ 7020ms
Retry Behavior.Max Retries Respected ✅ 17035ms
Deduplication.Generates Unique Uuids ✅ 51ms
Deduplication.Preserves Uuid On Retry ✅ 7016ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 12029ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7017ms
Deduplication.No Duplicate Events In Batch ✅ 35ms
Deduplication.Different Events Have Different Uuids ✅ 27ms
Compression.Sends Gzip When Enabled ✅ 21ms
Batch Format.Uses Proper Batch Structure ✅ 18ms
Batch Format.Flush With No Events Sends Nothing ✅ 12ms
Batch Format.Multiple Events Batched Together ✅ 33ms
Error Handling.Does Not Retry On 403 ✅ 4020ms
Error Handling.Does Not Retry On 413 ✅ 4019ms
Error Handling.Retries On 408 ✅ 5028ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 33ms
Request Payload.Flags Request Uses V2 Query Param ✅ 26ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 36ms
Request Payload.Flags Request Omits Authorization Header ✅ 33ms
Request Payload.Token In Flags Body Matches Init ✅ 22ms
Request Payload.Groups Round Trip ✅ 25ms
Request Payload.Groups Default To Empty Object ✅ 25ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 23ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 26ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 24ms
Request Lifecycle.No Flags Request On Init Alone ✅ 15ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 21ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 37ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 25ms
Retry Behavior.Retries Flags On 502 ✅ 322ms
Retry Behavior.Retries Flags On 504 ✅ 324ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 21ms

gewenyu99 and others added 2 commits November 5, 2026 12:47
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>
Comment thread .github/workflows/release.yml Resolved
Comment thread bin/docs_scripts/generate_markdown.py Resolved
Comment thread bin/docs_scripts/generate_markdown.py Resolved
Comment thread bin/docs_scripts/generate_markdown.py Resolved
Comment thread bin/docs_scripts/generate_markdown.py Resolved
gewenyu99 and others added 4 commits November 5, 2026 14:55
- 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>
@gewenyu99
gewenyu99 marked this pull request as ready for review November 10, 2026 19:36
@gewenyu99
gewenyu99 requested a review from a team as a code owner November 10, 2026 19:36
@gewenyu99
gewenyu99 requested review from eli-r-ph and turnipdabeets and removed request for a team November 10, 2026 19:36
@veria-ai

veria-ai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed ddfa6e8: 2 Should fix.

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")})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +125 to +128
- name: 'Set up Python'
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.13'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gewenyu99
gewenyu99 added this pull request to stack #969 November 11, 2026 18:56
@gewenyu99
gewenyu99 merged commit 8d3735a into main Nov 11, 2026
19 checks passed
@gewenyu99
gewenyu99 deleted the markdown-reference-adapter branch November 11, 2026 18:59
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