ionic-team / capacitor-docgen

Docs Readme Markdown and JSON Generator for Capacitor Plugins.

@capacitor/docgen

Docs Readme Markdown and JSON Generator for Capacitor Plugins.

• Designed specifically for generating docs for Capacitor plugins using TypeScript
• Generates docs data pulled from JSDocs within source code
• Replaces placeholders within existing README.md markdown files with the generated docs
• Outputs a json file of the raw docs data
• Ideal for formatted docs within Github and NPM readme landing pages
• If you're looking for an entire docs site generator we recommend TypeDoc instead

npm i @capacitor/docgen --save-dev

Example Readme File

# My Capacitor Plugin 🔌

The readme file can be formatted however you'd like. Just insert
the docgen placeholder elements where the index of the API methods,
and the API docs should go.

Below is an index of all the methods available.

<docgen-index></docgen-index>

## Custom Readme Content

Manage your readme content however, and on every `docgen` rebuild
it will leave the original content as is, but update the inner text 
of the docgen placeholder elements with the updated generated docs.

<docgen-api></docgen-api>

## Commit Your Readme 🚀

The benefit of this readme file is that is also acts as the landing 
page for the Github repo and NPM package, and the anchors within the 
docs can also be linked to and shared.

• Example Readme Output
• Example JSON Output

CLI

The easiest way to run docgen is to install @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.

package.json script

{
  "scripts": {
    "docgen": "docgen --api HapticsPlugin --output-readme README.md"
  }
}

API

The same API that's available to the CLI can also be imported from @capacitor/docgen.

Related

• Capacitor
• Capacitor Community Plugins

capacitor-docgen's Issues

Apple requires privacy descriptions to be specified in Info.plist for location information:

@capacitor/geolocation

https://capacitorjs.com/docs/apis/geolocation#ios

We need to add this manually to the info.plist file. I hope you'll add this to the Capacitor doc:

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs Location access for "some reason"!</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs Location access for "some reason"!</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>$(PRODUCT_NAME) needs Location access for "some reason"!</string>

JS Date types should not be included

We don't need to pull in the Date interface and all its methods

https://capacitorjs.com/docs/v3/apis/local-notifications#date

bug: wrong `reference types` in community plugins

The generated value in reference types always has the prefix @capacitor. However, community plugins have a different scope or no scope at all.

Example (see https://github.com/robingenz/capacitor-firebase/blob/main/packages/authentication/README.md#examples):

/// <reference types="@capacitor/firebase-authentication" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseAuthentication: {
      skipNativeAuth: false,
      providers: ["apple.com", "google.com"],
    },
  },
};

export default config;

/// <reference types="@capacitor/firebase-authentication" /> should be /// <reference types="@capacitor-firebase/authentication" />.

Doesn't account for identical autogenerated slugs

schedule() and Schedule generate the same URL fragment: #schedule

https://capacitorjs.com/docs/v3/apis/local-notifications#schedule

Do not show "Returns" for void functions

When docs are generated for void functions, this is what appears:

The Returns line should just be removed for void functions

Improve addListener generation

Can't link to the various addListener definitions, they all get melded together.

https://capacitorjs.com/docs/v3/apis/keyboard

bug: Non-accessible APIs from external dependencies are part of the output

Hi,
thank you very much for this helpful generator.
I have the following problem since version 0.1.1:
APIs of external dependencies are included, which are not available via the plugin API (definitions.ts).

Here you can find an example: https://github.com/robingenz/capacitor-firebase-authentication/pull/122/files

In this project I have increased the version of docgen to 0.1.1 and updated the markdown. There are now many interfaces included (partly also twice), which are not available at all.

bug: unused APIs from external dependencies are part of the output

I have the problem that external APIs that are NOT imported in the definitions.ts file are still part of the output of the generator.

Here you can find an example: capawesome-team/capacitor-firebase#430

I'm using version 0.2.1 of the generator.

Use markdown link instead of <a> element

Currently we are busy refactoring the Capacitor Google Maps plugin. One of the improvements is better documentation. The fork (WIP) can be found here: https://github.com/DutchConcepts/capacitor-google-maps/tree/next

I use docsify to generate an organized documentation website based on the markdown documentation (can be found in the ./docs folder in that fork). The API reference is generated with this plugin. This works really well, for which I commend you 👏.

The generated website (GitHub pages) can be found here.

As can be seen, the links generated by docgen are broken, because they are a <a> element instead of a markdown link.

It would be solved by changing:
<code><a href="#foobar">FooBar</a></code>
to
<code>[FooBar](#foobar)</code>

The docsify team said the following:

You need generate markdown syntax. Such as

[MyClass](#MyClass)

It will not be compiled if it is HTML.

Therefore I hope it can be solved in this plugin. As far as I can see now, I don't think this change does have any drawbacks, so it would make sense to implement it like this. But please do share your opinion about this.

Support types

interfaces and enums are supported, but types are not. In the following link, it is not possible to know what ScreenReaderStateChangeListener is: https://capacitorjs.com/docs/v3/apis/screen-reader#addlistener

Seems to match type by name only

https://capacitorjs.com/docs/v3/apis/local-notifications#schedule

"Schedule" shouldn't be linked to the Schedule type.

source: https://github.com/ionic-team/capacitor-plugins/blob/main/local-notifications/src/definitions.ts#L47

feat: support for other file interfaces that called "extends"

Right now, it does not support types called from other files.
Like: https://github.com/capacitor-community/admob/blob/feat/v3/src/definitions.ts

I believe this will help in the refactoring of many of the plugins once it is supported.

bug: return value is always "any"

Hello,

I created a new capacitor plugin: https://github.com/paystory-de/capacitor-headwind-mdm
And whenever I run this docgen command it generates a wonderful README.md - except the returns.
Its always:

isConnected() => any

And

Returns: any

Any ideas? 😉