Table of contents
Overview
Create abstract api documentation nodes using props parsed from structured-types/api
. Can be used to generate markdown or html documentation pages.
Installation
yarn add @structured-types/api-readme --dev
Usage
You can launch directly from the command-line ie yarn run api-readme
or from your package.json
file by adding a script to launch the command line documentation tool.
import reactPlugin from '@structured-types/react-plugin';
import propTypesPlugin from '@structured-types/prop-types-plugin';
import { DocsOptions, parseFiles } from '@structured-types/api';
import {
propsToDocumentation,
DocumentationOptions,
} from '@structured-types/api-docs';
export const extractProps = (
files: string[],
config?: DocsOptions & DocumentationOptions,
): ReturnType<typeof propsToDocumentation> => {
/**
* parse props using @structured-types/api
*/
const props = parseFiles(files, {
collectSourceInfo: true,
collectHelpers: true,
// use react typescript and react prop-types extensions
plugins: [propTypesPlugin, reactPlugin],
...config,
});
return propsToDocumentation(props, config);
};
Configuration
You can configure api-docs by passing a configuration object or with an external file.
api-docs uses cosmiconfig for external configurations in a file. The configuration is loaded by precedence:
- a
api-docs
key in your package.json file - a
.api-docsrc
file for JSON or YAML configuration - a
.api-docsrc.json
,.api-docsrc.yaml
,.api-docsrc.yml
file for JSON or YAML configuration - a
.api-docsrc.js
,.api-docsrc.cjs
,api-docs.config.js
orapi-docs.config.cjs
javascript file that exports a configuration object usingmodule.exports
.
Configuration examples
Javascript:
module.exports = {
visible: ['LineChart'],
sections: ['props'],
collapsed: ['ViewProps'],
};
JSON:
{
"visible": ["LineChart"],
"sections": ["props"],
"collapsed": ["ViewProps"],
}
YAML:
visible:
- LineChart
sections:
- props
collapsed:
- ViewProps
Sections
You can show/hide or provide a custom configuration for the documentation sections.
1. List configuration
The simplest way to only display some sections is by listing them in a list of strings. All sections that are not in the list will be removed.
Javascript:
module.exports = {
sections: ['title', 'props'],
};
JSON
{
"sections": ["title", "props"],
};
YAML
sections:
- title
- props
2. Object configuration
Providing an object configuration allows you to modify the title and other properties of the section. When using a javascript configuration file, you can also provide a callback function for custom section titles or content.
Javascript:
module.exports = {
sections: {
title: {
title: 'Component',
render: (prop) => [
{
kind: 5,
children: [{ kind: 6, value: `The Name is: ${prop.name}` }],
},
],
},
props: {
title: 'Props'
},
type: {
hidden: true,
},
examples: {
title: (prop) =>
prop.examples && prop.examples.length > 1 ? 'Samples' : 'Sample',
},
};
JSON
{
"sections": {
"props", {
"title": "Props"
},
"type": {
"hidden": true,
},
},
};
YAML
sections:
title:
title: 'Component'
type:
hidden: true
title: 'Types'
Columns
You can show/hide or provide a custom configuration for the columns in the properties table.
1. List configuration
The simplest way to only display some columns is by listing them in a list of strings. All columns that are not in the list will be removed.
Javascript:
module.exports = {
columns: ['name', 'type'],
};
JSON
{
"columns": ["name", "type"],
};
YAML
columns:
- name
- type
2. Object configuration
Providing an object configuration allows you to modify the column titles and other properties of the properties table. When using a javascript configuration file, you can also provide callback for custom column titles or content.
Javascript:
module.exports = {
columns: {
name: {
title: 'Property',
render: (name, prop) => {
if (name === 'name') {
// custom render the "name" column cells
return [
{
kind: 5,
children: [{ kind: 6, value: `The Name is: ${prop.name}` }],
},
];
}
// all other cells render as default
return undefined;
},
},
parents: {
hidden: true,
},
description: {
title: (prop) => `${prop.name} props`,
},
},
};
JSON
{
"columns": {
"name": {
"title": "Property"
},
"parents": {
"hidden": true
}
}
}
YAML
columns:
name:
title: 'Property'
parents:
hidden: true
Multiple elements
You can have multiple elements configured within the same configuration file. For example, you have two components to document LineChart.tsx
and RadarChart.tsx
:
Javascript
module.exports = {
sections: ['props'],
elements: {
'LineChart.tsx': {
sections: ['description', 'props'],
visible: ['LineChart'],
},
'RadarChart.tsx': {
visible: ['RadarChart'],
}
}
};
JSON
module.exports = {
"sections": ["props"],
"elements": {
"LineChart.tsx": {
"sections": ["description", "props"],
"visible": ["LineChart"],
},
"RadarChart.tsx": {
"visible": ["RadarChart"],
}
}
};
YAML:
sections:
- props
elements:
LineChart.tsx:
sections:
- description
- props
visible:
- LineChart
RadarChart.tsx:
visible:
- RadarChart
Matching the elements uses micromatch and you can specify wildcards for matching groups of files relative to the folder of the configuration file.
Exact Match
The following element key will match exactly the file src/components/Toggle/Toggle.tsx
module.exports = {
elements: {
'src/components/Toggle/Toggle.tsx': {
sections: {
props: {
hidden: true,
},
},
},
},
};
File Name Match
The following element key will match the file Toggle.tsx
regardless of its location within the folders structure
module.exports = {
elements: {
'Toggle.tsx': {
sections: {
props: {
hidden: true,
},
},
},
},
};
Match nested sub-folders
The following element key will match any files in src/components
and all of its subfolders
module.exports = {
elements: {
'src/components/**': {
sections: {
props: {
hidden: true,
},
},
},
},
};
Match single folder
The following element key will match any files in the src/components
folder
module.exports = {
elements: {
'src/components/*': {
sections: {
props: {
hidden: true,
},
},
},
},
};
API
NodeKind
enum
Documentation node kinds
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
properties
Name | Type | Value |
---|---|---|
Table* |
number |
1 |
TableRow* |
number |
2 |
TableCell* |
number |
3 |
Heading* |
number |
4 |
Paragraph* |
number |
5 |
Text* |
number |
6 |
Bold* |
number |
7 |
Emphasis* |
number |
8 |
Link* |
number |
9 |
Code* |
number |
10 |
InlineCode* |
number |
11 |
Block* |
number |
12 |
Collapsible* |
number |
13 |
propsToDocumentation
async function
defined in @structured-types/api-docs/packages/api-docs/src/props-to-nodes.ts
parameters
Name | Type | Description |
---|---|---|
props* |
|
properties parsed from structured-types/api
|
options* |
DocumentationOptions |
page generation options |
returns |
Promise <DocumentationNode []> |
DocumentationNode
interface
Base documentation node
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
properties
Name | Type | Description |
---|---|---|
kind* |
NodeKind |
Documentation node kinds |
DocumentationNodeWithChildren
interface
Documentation node with children
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Description |
---|---|---|
children* |
DocumentationNode [] |
|
kind* |
NodeKind |
Documentation node kinds |
DocumentationNodeWithValue
interface
Documentation node with a value
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Description |
---|---|---|
value* |
string |
|
kind* |
NodeKind |
Documentation node kinds |
apiDocsConfig
async function
Read the api-docs configuration file
defined in @structured-types/api-docs/packages/api-docs/src/index.ts
parameters
Name | Type | Description |
---|---|---|
fileName* |
string |
the file that is being analyzed, will be used the starting folder to search for configuration files. |
configFileName |
string |
pass directly the configuration file name |
options |
|
Options for configuration file |
returns |
Promise <CosmiconfigResult > |
page generation options from the config file |
TableNode
interface
Table node, where the first row is a table header row
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Table |
NodeKind |
1 |
children* |
TableRowNode [] |
TableRowNode
interface
Table row node - can be a header or data row
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
TableRow |
NodeKind |
2 |
children* |
TableCellNode [] |
TableCellNode
interface
Table cell node, the content is a list of child nodes
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
TableCell |
NodeKind |
3 |
children* |
DocumentationNode [] |
DocumentationNodeWithChildren |
getRepoPath
async function
defined in @structured-types/api-docs/packages/api-docs/src/package-info/package-info.ts
parameters
Name | Type | Description |
---|---|---|
fs* |
|
|
filePath* |
string |
file path to start the search for a package.json |
returns |
Promise <RepoPathReturnValue > |
HeadingNode
interface
Heading node with a depth parameter, the content is a list of child nodes
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Heading |
NodeKind |
4 |
depth* |
number |
||
children* |
DocumentationNode [] |
DocumentationNodeWithChildren |
ParagraphNode
interface
Paragraph node, the content is a list of child nodes
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Paragraph |
NodeKind |
5 |
children* |
DocumentationNode [] |
DocumentationNodeWithChildren |
TextNode
interface
Text node, the content string is in the value field
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Text |
NodeKind |
6 |
value* |
string |
DocumentationNodeWithValue |
BoldNode
interface
Bold/Strong node, the content is a list of child nodes
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Bold |
NodeKind |
7 |
children* |
DocumentationNode [] |
DocumentationNodeWithChildren |
EmphasisNode
interface
Emphasis/Italic node, the content is a list of child nodes
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Emphasis |
NodeKind |
8 |
children* |
DocumentationNode [] |
DocumentationNodeWithChildren |
LinkNode
interface
Link node with url property, the content is a list of child nodes
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Link |
NodeKind |
9 |
url |
string |
||
loc |
|
||
children* |
DocumentationNode [] |
DocumentationNodeWithChildren |
CodeNode
interface
Code node, the content string is in the value field
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
Code |
NodeKind |
10 |
value* |
string |
DocumentationNodeWithValue |
InlineCodeNode
interface
Inline code node, the content string is in the value field
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
extends
properties
Name | Type | Parent | Default |
---|---|---|---|
kind* |
InlineCode |
NodeKind |
11 |
value* |
string |
DocumentationNodeWithValue |
DocumentationOptions
type
Document page generation options
defined in @structured-types/api-docs/packages/api-docs/src/types.ts
properties
Name | Type | Description |
---|---|---|
collapsed |
string [] |
List of type names, that should not be expanded. For example, some internal React objects can be kept just as a string and will not be detailed in the documentation, instead of listing their internal properties. |
extensions |
string [] |
List of plugins (or extensions). For example, for a react library, you can specify to include only react components, but not any additional types or utilities. |
visible |
string [] |
List of type names, that should be "visible". This will limit which of the parsed props to be documented. |
columns |
ColumnName [] | Partial <Record <ColumnName , ColumnConfig >> |
Sections can be configured as an array of the visible sections, or an object with keys the section name, and values a configuration object |
sections |
SectionName [] | Partial <Record <SectionName , SectionConfig >> |
Sections can be configured as an array of the visible sections, or an object with keys the section name, and values a configuration object |
skipInherited |
boolean |
Whether to skip properties that are "inherited", or "composed". For example, type OwnProps = { x: number } & React.LineProps will only output the x property and skip the inherited React library properties. |
fs |
|
virtual file system for use in browser |