Skip to content

docs: generate the SDK reference as Markdown with dart doc - #705

Merged
gewenyu99 merged 13 commits into
mainfrom
docs/markdown-reference-adapter
Nov 11, 2026
Merged

gewenyu99 merged 13 commits into
mainfrom
docs/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).

  • dart doc, which ships with the Dart SDK, writes one page per symbol and an index.json. scripts/generate_markdown_reference.py reads them with BeautifulSoup and markdownify (pinned in scripts/requirements.txt, docs only) and 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 docs/getting-started.md and a step in publish.yml.
  • 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.
  • The migration page comes from posthog_flutter/MIGRATION.md, where Flutter keeps its guide.

💚 How did you test it?

  • Regenerating reproduces the pages in the next PR. The publish 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 scripts/generate-markdown-reference.dart, which renders the public API with dartdoc_modern and groups it by PostHog/sdk-specs capability. The release workflow regenerates references/ after each release.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@gewenyu99 gewenyu99 self-assigned this Nov 5, 2026

@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 427eac2: 3 Should 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 .github/workflows/publish.yml Resolved
Comment thread .github/workflows/publish.yml Resolved
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

posthog-flutter Compliance Report

Date: 2026-11-09 18:36:07 UTC
Duration: 96751ms

✅ All Tests Passed!

45/45 tests passed


Capture Tests

✅ 29/29 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 139ms
Format Validation.Event Has Uuid ✅ 118ms
Format Validation.Event Has Lib Properties ✅ 115ms
Format Validation.Distinct Id Is String ✅ 114ms
Format Validation.Token Is Present ✅ 114ms
Format Validation.Custom Properties Preserved ✅ 115ms
Format Validation.Event Has Timestamp ✅ 116ms
Retry Behavior.Retries On 503 ✅ 5327ms
Retry Behavior.Does Not Retry On 400 ✅ 2115ms
Retry Behavior.Does Not Retry On 401 ✅ 2117ms
Retry Behavior.Respects Retry After Header ✅ 8125ms
Retry Behavior.Implements Backoff ✅ 15446ms
Retry Behavior.Retries On 500 ✅ 5224ms
Retry Behavior.Retries On 502 ✅ 5225ms
Retry Behavior.Retries On 504 ✅ 5223ms
Retry Behavior.Max Retries Respected ✅ 15437ms
Deduplication.Generates Unique Uuids ✅ 123ms
Deduplication.Preserves Uuid On Retry ✅ 5223ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10334ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5230ms
Deduplication.No Duplicate Events In Batch ✅ 122ms
Deduplication.Different Events Have Different Uuids ✅ 115ms
Compression.Sends Gzip When Enabled ✅ 115ms
Batch Format.Uses Proper Batch Structure ✅ 112ms
Batch Format.Flush With No Events Sends Nothing ✅ 108ms
Batch Format.Multiple Events Batched Together ✅ 122ms
Error Handling.Does Not Retry On 403 ✅ 2115ms
Error Handling.Does Not Retry On 413 ✅ 2117ms
Error Handling.Retries On 408 ✅ 5222ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 11ms
Request Payload.Flags Request Uses V2 Query Param ✅ 8ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 9ms
Request Payload.Flags Request Omits Authorization Header ✅ 8ms
Request Payload.Token In Flags Body Matches Init ✅ 9ms
Request Payload.Groups Round Trip ✅ 9ms
Request Payload.Groups Default To Empty Object ✅ 8ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It ✅ 8ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 8ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 9ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 8ms
Request Lifecycle.No Flags Request On Init Alone ✅ 4ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 111ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 15ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 8ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 113ms

gewenyu99 and others added 2 commits November 5, 2026 12:55
dart doc ships with the Dart SDK, so the pinned dartdoc_modern tool and its
analyzer conflict go away. The script reads index.json for the symbols and each
page's signature and description with BeautifulSoup and markdownify, pinned in a
docs-only requirements file, with no regex.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Escaping for MDX now touches prose only, so code shows { and } as written.
Signatures drop labels such as "getter/setter pair" and the spaces dartdoc's
line breaks leave inside brackets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gewenyu99 and others added 3 commits November 5, 2026 14:25
ghcommit-action passes an untracked folder to ghcommit as one path, which fails
on the first release that writes references/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The posthog-capability lines showed up in IDE hover help for every SDK user.
The generator now reads the map and fails on stale, unknown or unmapped labels.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@turnipdabeets turnipdabeets 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.

[nit] The title and description still say dartdoc_modern and posthog-capability: tags — the code now uses plain dart doc and docs/capabilities.json.

Comment thread .github/workflows/publish.yml Resolved
Comment thread .github/workflows/publish.yml Resolved
Comment thread .github/workflows/publish.yml Resolved
The publish job had neither, so flutter pub get, dart doc and pip install
would fail on the first release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gewenyu99 gewenyu99 changed the title docs: generate the SDK reference as Markdown with dartdoc_modern docs: generate the SDK reference as Markdown with dart doc Nov 5, 2026
gewenyu99 and others added 3 commits November 5, 2026 15:41
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>
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>
Comment thread scripts/generate_markdown_reference.py Outdated
write(f"posthog-flutter-{major}.md", [front_matter(title, body), *body])
if declared >= major:
write("posthog-flutter-reference.md", [front_matter("PostHog Flutter SDK", body), *body])
if guides := sorted((ROOT / "docs").glob("migration-*.md"), reverse=True):

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.

[suggestion] Flutter's guide lives at posthog_flutter/MIGRATION.md (#637), so this glob never matches and no migration page is generated — that's also why PostHog/posthog.com#22003 has no Flutter "Migration guides" link. Could we read that path?

Suggested change
if guides := sorted((ROOT / "docs").glob("migration-*.md"), reverse=True):
if guides := [g for g in [PKG / "MIGRATION.md"] if g.exists()]:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes, we'll read from that path and regenerate from the latest branch. It also regenerates on every release, so any minor drift gets picked up then. Thanks!

gewenyu99 and others added 3 commits November 6, 2026 16:41
The guide lives next to the package, not under docs/, so the generator never
found it and wrote no migration page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The loop that drops dartdoc's "final" and "getter/setter pair" tags reused
the label parameter's name, so every member with one of those tags got the
removed tag, `<></>`, as its heading.

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 d8bb367: 2 Should fix.

Comment on lines +175 to +178
- uses: axi92/flutter-action@36d2c2625bac6ea011cd7808d2a01bd8a7e5c766 # feature/pin-action-sha @ 2026-04-30
if: steps.commit-version-bump.outputs.commit-hash != ''
with:
channel: 'stable'

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 · Apply best-effort handling to every reference step

When Flutter setup, Python setup, or the reference commit fails, the added steps fail the release job because they lack continue-on-error. The tag has already been pushed, so the workflow emits release-preparation failure alerts while publishing proceeds independently. Extend best-effort handling to the reference setup and commit steps.

Comment thread docs/getting-started.md

The Flutter SDK runs in iOS, Android, macOS, and web apps.

To send your first event, add `posthog_flutter`, then call `setup` once before `runApp` with your project token and host from your [project settings](https://app.posthog.com/project/settings).

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 the required JavaScript initialization for web

For a fresh Flutter web app, these instructions leave window.posthog undefined: PosthogFlutterWeb.setup only binds to an existing JavaScript SDK and never initializes it. Subsequent capture and identify calls therefore send no events despite following the guide. Add the required posthog-js loading and initialization steps for web.

@gewenyu99
gewenyu99 added this pull request to stack #719 November 11, 2026 18:56
@gewenyu99
gewenyu99 merged commit 2398895 into main Nov 11, 2026
32 checks passed
@gewenyu99
gewenyu99 deleted the docs/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