@rdlabo/capacitor-docgen is an independently maintained enhancement fork of Ionic's @capacitor/docgen. It keeps the upstream CLI, Markdown placeholders, output helpers, and exported functions, while extending the parser result and generated content with interface inheritance.
The comparison in these docs is pinned to @rdlabo/capacitor-docgen@0.4.1 and upstream @capacitor/docgen@0.3.1, the current npm releases. It does not imply that the fork is an official Ionic package.
npm install --save-dev @rdlabo/capacitor-docgenUse the same docgen command and flags as upstream:
npx docgen --api MyPlugin --output-readme README.md --output-json dist/docs.jsonThe input README must already contain the placeholders that docgen updates:
<docgen-index></docgen-index>
<docgen-api></docgen-api>Do not install both packages as direct dependencies in one project: both publish the docgen binary. Choose the fork when inherited interface members must appear in generated documentation.
Upstream records only the members written directly in an interface. The fork also reads a TypeScript extends clause and appends methods and properties from the resolved base interface.
export interface SharedOptions {
requestId?: string;
}
export interface CreateOptions extends SharedOptions {
value: string;
}
export interface MyPlugin {
create(options: CreateOptions): Promise<void>;
}With the fork, the generated CreateOptions table contains both value and requestId. The fork can also resolve a base named through a type alias when that alias points to an interface.
The released fork README says to add an @extends JSDoc tag. That instruction is stale for v0.4.1: the implementation reads the TypeScript heritage clause directly and does not use the tag to resolve inheritance. Write valid TypeScript extends; an @extends tag is not required.
See Differences from upstream for the exact changed surfaces and current limitations.
Full documentation: https://docs.rdlabo.dev/projects/capacitor-docgen
The easiest way to run docgen is to install @rdlabo/capacitor-docgen as a dev dependency
and add the command to the package.json scripts. In the example below,
HapticsPlugin is the primary interface:
docgen --api HapticsPlugin --output-readme README.md| Flag | Alias | Description |
|---|---|---|
--api |
-a |
The name of the primary application programming interface. Required |
--output-readme |
-r |
Path to the markdown file to update. Note that the file must already exist. Required |
--output-json |
-j |
Path to write the raw docs data as a json file. |
--project |
-p |
Path to the project's tsconfig.json file, same as the project flag for TypeScript's CLI. By default it'll attempt to find this file. |
{
"scripts": {
"docgen": "docgen --api HapticsPlugin --output-readme README.md"
}
}The same API that's available to the CLI can also be imported from @rdlabo/capacitor-docgen.
An open, non-draft pull request can be published to the npm beta dist-tag after its Validation and Package Candidate workflows pass. A repository owner or maintainer must add a comment whose entire body is:
/beta
The request authorizes only the pull request head SHA that existed when the comment was added. The workflow revalidates the owner or maintainer permission and head SHA immediately before publishing. Any new commit requires CI to pass again and a fresh owner or maintainer /beta comment. Fork pull requests are supported. Pull requests that change a release-gating workflow cannot be beta-published until those workflow changes land on main.
Beta versions use <base>-beta.pr<PR number>.sha<12-character SHA>. The candidate is built in a read-only workflow without npm publishing credentials. The privileged release workflow publishes only the validated immutable package artifact with lifecycle scripts disabled. A notification failure cannot invalidate a successful npm publish.
When a pull request is merged into main, it is automatically published to beta only after the required CI and Package Candidate succeed for that exact merge commit. Direct pushes to main do not publish a candidate.
Only npm run release creates a release tag. Stable vX.Y.Z tags publish to npm latest; revision/prerelease tags publish to next. Neither beta nor next publishing changes the npm latest dist-tag.