@structured-types/api-docs
v3.46.12
Published
Create api documentation nodes using structured-types/api
Downloads
51
Maintainers
Readme
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*
| PropTypes
[string
]: interface
kind
: PropKind
.String
, PropKind
.Number
, PropKind
.Boolean
, PropKind
.Union
, PropKind
.Enum
, PropKind
.Tuple
, PropKind
.Rest
, PropKind
.Undefined
, PropKind
.Unknown
, PropKind
.Null
, PropKind
.Function
, PropKind
.Void
, PropKind
.Class
, PropKind
.Interface
, PropKind
.Type
, PropKind
.Array
, PropKind
.Any
, PropKind
.Index
, PropKind
.Constructor
, PropKind
.Getter
, PropKind
.Setter
, PropKind
.BigInt
, PropKind
.Component
, PropKind
.Object
, PropKind
.Namespace
, PropKind
.RegEx
name
: string
alias
: string
parent
name
*: string
loc
: SourceLocationloc
filePath
: string
loc
: SourcePositionsoptional
: boolean
readonly
: boolean
abstract
: boolean
async
: boolean
visibility
: "private"
| "protected"
| "public"
static
: boolean
type
: string
extension
: string
description
: string
fires
: string
[]see
: string
[]examples
: JSDocExample
[]tags
: JSDocPropTag
[]summary
: string
deprecated
: string
| true
ignore
: boolean
usage
: type
[]__helpers
: Record
<string
, PropType
>__diagnostics
: PropDiagnostic
[] | 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
| ConfigOptions
fs
fileExists
*: function (filePath
*: ) => Promise
<boolean
>readDirectory
*: function (path
*: ) => Promise
<string
[]>isDirectory
*: function (path
*: ) => Promise
<boolean
>readFile
*: function (filePath
*: ) => Promise
<(string
, null
)>cwd
*: function () => string
elementId
: string
cosmic
: Omit
<CosmicOptions
, "fs"
> | 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*
| STFS
fileExists
*: function (filePath
*: string
) => Promise
<boolean
>readDirectory
*: function (path
*: string
) => Promise
<string
[]>isDirectory
*: function (path
*: string
) => Promise
<boolean
>readFile
*: function (filePath
*: string
) => Promise
<(string
, null
)>cwd
*: function () => string
| |
| 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
| SourceLocation
filePath
: string
loc
start
*line
*: col
*: end
*line
*: col
*: | | |
| 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
| STFS
fileExists
*: function (filePath
*: string
) => Promise
<boolean
>readDirectory
*: function (path
*: string
) => Promise
<string
[]>isDirectory
*: function (path
*: string
) => Promise
<boolean
>readFile
*: function (filePath
*: string
) => Promise
<(string
, null
)>cwd
*: function () => string
| virtual file system for use in browser |