@rspress/plugin-api-docgen
The plugin is used to generate api document description automatically, powered by react-docgen-typescript and documentation.
Install
npm add @rspress/plugin-api-docgen -D
Usage
First of all, you need to add following config:
// rspress.config.ts
import path from 'path';
import { defineConfig } from 'rspress';
import { pluginApiDocgen } from '@rspress/plugin-api-docgen';
export default defineConfig({
plugins: [
pluginApiDocgen({
entries: {
button: './src/index.ts',
},
apiParseTool: 'react-docgen-typescript',
}),
],
});
Then you can use API component to inject api documentation to your mdx file:
## API
This is API Table
<API moduleName="button" />
Config
The plugin accepts an object, which has the following types:
interface Options {
entries?: Record<string, string>;
apiParseTool?: 'react-docgen-typescript' | 'documentation';
appDir?: string;
parseToolOptions?: ParseToolOptions;
}
appDir
appDir
is used to configure the base directory for parsing,default process.cwd()
.
entries
entries
is used to configure the basic info for parsing.
- key is an identifier that serves as the
moduleName
attribute of the API component.
- value is the relative path to the parsed file.
apiParseTool
apiParseTool
is used to choose the tool for parsing,default react-docgen-typescript
:
react-docgen-typescript
is used for component library scenarios, only props will be parsed to generate tables.
export type ButtonProps = {
/**
* Whether to disable the button
*/
disabled?: boolean;
/**
* Type of Button
* @default 'default'
*/
size?: 'mini' | 'small' | 'default' | 'large';
};
export const Button = (props?: ButtonProps) => {};
The above is a standard writeup where ButtonProps
will be extracted into the form and Button
will be used as the form title.
If you use the default export, the filename will be used as the form title.
Notice that export features declared elsewhere are not available.
const A = () => {};
export { A }; // wrong
export default A; // wrong
export const B = () => {}; // right
export default () => {}; // right
The generated content is as follows:
### ButtonTest
| Props | Description | Type | Default |
| :------: | :---------------------------: | :-----------------------------------------: | :---------: |
| disabled | Whether to disable the button | `boolean` | `-` |
| size | Type of Button | `"mini" \| "small" \| "default" \| "large"` | `'default'` |
WARNING
If React types are used in Props, you need to add the types in tsconfig.json, otherwise the types will not be resolved under the React namespace.
{
"compilerOptions": {
"types": ["react"]
}
}
The best way is that you import the type directly:
import { FC } from 'react';
documentation
is used in tool library scenarios to parse JSDoc annotations.
Here is a greet function with JSDoc annotations.
/**
* Greet function that returns a greeting message.
* @param {string} name - The name of the person to greet.
* @param {string} [greeting='Hello'] - The greeting to use.
* @returns {string} The greeting message.
*/
function greet(name: string, greeting = 'Hello') {
return `${greeting}, ${name}!`;
}
The generated content is as follows:
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
## greet
Greet function that returns a greeting message.
### Parameters
- `name` **[string][1]** The name of the person to greet.
- `greeting` **[string][1]** The greeting to use. (optional, default `'Hello'`)
Returns **[string][1]** The greeting message.
[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
parseToolOptions
parseToolOptions
is used to pass options to the corresponding parse tool, whose types are as follows:
type ParseToolOptions = {
'react-docgen-typescript'?: ParserOptions & {
tsconfigPath?: Record<string, string>;
compilerOptions?: Record<string, ts.CompilerOptions>;
};
documentation?: DocumentationArgs;
};
Please refer to ParserOptions and DocumentationArgs to learn about available options.
If the parser is react-docgen-typescript
, the withDefaultConfig
method is used by default to create a parser instance. If tsconfigPath
or compilerOptions
is configured, tsconfigPath
and compilerOptions
can be set separately for each entry
, the withCompilerOptions
and withCustomConfig
methods are used to create the parser instance respectively. See Custom Parsers for details.