@fluentui/api-docs
v8.2.25
Published
Transforms API Extractor .api.json files into .page.json files
Downloads
314
Maintainers
Keywords
Readme
@fluentui/api-docs
Processes package-name.api.json
files generated by API Extractor into ComponentName.page.json
files used to populate API reference tables, mainly in the Fluent UI website's Controls section.
Using the tool
- In each API item which should be included on the website (see Limitations below for supported item types), include a
{@docCategory PageName}
annotation in its top-level doc comment. If the item is related to a specific component,PageName
should be the name of the component. Otherwise, you can use either the name of the item or a general category that it falls under.
/**
* Comment about the props
* {@docCategory Foo}
*/
interface FooProps {}
Add a config and build step to run API Extractor on your package. (Fluent UI has a shared config extended by each package's config.)
Somewhere in your repo (probably in the package that displays the documentation), add a build step to invoke the
generatePageJsonFiles
API. For the config object, seeIPageJsonOptions
in this file for docs and this file for an example.
const { generatePageJsonFiles } = require('@fluentui/api-docs');
const config = {}; // your config here
generatePageJsonFiles(config);
- To render the info from
*.page.json
files, you can either useApiReferencesTableSet
from@fluentui/react-docsite-components
, or use its logic as a template for your own control.
Limitations
Supported API items
Documenting the following API items/types is supported:
- Interfaces
- Type aliases
- Classes
- Enums
These API items/types are not supported currently (PRs welcome):
- Functions (including function components)
- Constants
Markdown
If you're using ApiReferencesTableSet
for rendering the output, top-level doc comments have full markdown support, but individual prop comments have limited support (currently just inline code blocks) due to performance concerns. (May not apply if you've written your own renderer.)
Prop comments
API Extractor has a particular format required for certain types of doc comments and will fail at build time if this format is not followed. There are also a few suggested best practices.