docs: add @since TypeDoc tags, drop versioned documentation#936
docs: add @since TypeDoc tags, drop versioned documentation#936barjin wants to merge 10 commits into
@since TypeDoc tags, drop versioned documentation#936Conversation
Annotate every top-level symbol, but annotate a member only when it was added in a later release than its parent. A member introduced alongside its parent is already covered by the parent's `@since`, so repeating it on every field was noise. Removes 417 redundant tags (1056 -> 639). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
the
t-tooling
|
This is what the page from above looks like after recent changes: 
Wdyt @janbuchar @B4nan ? (PS: note that small mismatches can happen because of the automatic annotation script. The |
B4nan
left a comment
B4nan
left a comment
There was a problem hiding this comment.
we should add the claude.md here and mention this there, otherwise i wouldnt trust the agents to do this consistently. also its a bit unfortunate that now you need to write a version before it gets released (usually it will be a feature bump, given new options/methods are added, but not always).
| label: 'GitHub', | ||
| }, | ||
| { | ||
| type: 'docsVersionDropdown', |
There was a problem hiding this comment.
i thought we agreed to keep majors versioned as before, so we still want the version switcher
There was a problem hiding this comment.
Now, this is a fair discussion point.
The current client docs only have the latest and next versions. Since the last v1 version is 5 years old (and has ~100 downloads, compared to 200k downloads on the v2 latest), I don't think it makes much sense to revive the v0 and v1 docs for this project. Perhaps for other projects, it would make more sense.
otherwise i wouldnt trust the agents to do this consistently
I have made a script that adds the @since tags from TypeDoc and git tags, so it's fairly deterministic.
its a bit unfortunate that now you need to write a version before it gets released
See the original PR description - perhaps we could run the aforementioned script in CI and have it create a PR with the @since tags on release?
Regarding versioning, should we keep the next version to keep the new symbols away from the main live docs? Or should we disable versioning altogether, write @since Added in next manually to each new symbol, and have it replaced on release by the script from above?
Also (apify-client-js specific) - could the autogenerated clients solve any of this for us in the future?
|
btw can we also render the |
Yes, here's the issue. |
|
The recent changes to the Typedoc plugin update rendering of the other tags as well (see 
|
Improves rendering of @-prefix tags in the documentation. See discussion under #936 for more info.
|
✅ The link checker did not find any broken links. See more at https://github.com/apify/apify-client-js/actions/runs/29906432450#summary-88878887004 |
Restores the versioned_docs/version-2 snapshot and the navbar version dropdown that this branch had dropped, so the reference site keeps its stable (latest release) and next (unreleased master) split alongside the new @SInCE tags. Fixes the release workflow's version-docs job so it wipes every previous snapshot instead of only the one matching the current major, since we only ever want to keep the latest stable snapshot around. Adds a CLAUDE.md note documenting the @SInCE convention and the stable/next split, per review feedback on #936.
|
@janbuchar do you think we could use the API extractor (that's already in, e.g., Crawlee) to find new symbols in a new release and auto-annotate these with the |
4 participants
Drops the Docusaurus-based versioned documentation and adds the
@sincetags to the JSDoc blocks. These are rendered as shown below ⬇️The main issue remains the need for manual updates of the
@sincetags on new symbols. The initial seeding was done by a script - perhaps we could add this to the CI?This is an experimental PR as a follow-up to an internal Tooling team discussion.