Repository navigation
docs: generate the SDK reference as Markdown with dart doc - #705
Conversation
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>
There was a problem hiding this comment.
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.
posthog-flutter Compliance ReportDate: 2026-11-09 18:36:07 UTC ✅ All Tests Passed!45/45 tests passed Capture Tests✅ 29/29 tests passed View Details
Feature_Flags Tests✅ 16/16 tests passed View Details
|
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>
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
left a comment
There was a problem hiding this comment.
[nit] The title and description still say dartdoc_modern and posthog-capability: tags — the code now uses plain dart doc and docs/capabilities.json.
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>
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>
| 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): |
There was a problem hiding this comment.
[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?
| if guides := sorted((ROOT / "docs").glob("migration-*.md"), reverse=True): | |
| if guides := [g for g in [PKG / "MIGRATION.md"] if g.exists()]: |
There was a problem hiding this comment.
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!
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>
PR overviewNo security issues were found in this pull request. Reviews
|
| - uses: axi92/flutter-action@36d2c2625bac6ea011cd7808d2a01bd8a7e5c766 # feature/pin-action-sha @ 2026-04-30 | ||
| if: steps.commit-version-bump.outputs.commit-hash != '' | ||
| with: | ||
| channel: 'stable' |
There was a problem hiding this comment.
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.
|
|
||
| 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). |
There was a problem hiding this comment.
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.
💡 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 anindex.json.scripts/generate_markdown_reference.pyreads them with BeautifulSoup and markdownify (pinned inscripts/requirements.txt, docs only) and 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 step inpublish.yml..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.posthog_flutter/MIGRATION.md, where Flutter keeps its guide.💚 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