Table of contents

- Overview
- Installation
- Usage
- Configuration
- Configuration examples
- Sections
- 1. List configuration
- 2. Object configuration
- Columns
- 1. List configuration
- 2. Object configuration
- Multiple elements
- Exact Match
- File Name Match
- Match nested sub-folders
- Match single folder
- API
- NodeKind
- propsToDocumentation
- DocumentationNode
- DocumentationNodeWithChildren
- DocumentationNodeWithValue
- apiDocsConfig
- TableNode
- TableRowNode
- TableCellNode
- getRepoPath
- HeadingNode
- ParagraphNode
- TextNode
- BoldNode
- EmphasisNode
- LinkNode
- CodeNode
- InlineCodeNode
- DocumentationOptions

Overview

Create abstract api documentation nodes using props parsed from structured-types/api. Can be used to generate markdown or html documentation pages.

Installation

``sh
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.

`ts
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 => {
/**
* 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 or api-docs.config.cjs javascript file that exports a configuration object using module.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.

!sections

$3

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

$3

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.

$3

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

$3

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.

$3

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,
},
},
},
},
};

$3

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,
},
},
},
},
};

$3

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,
},
},
},
},
};

$3

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: SourceLocation

loc

filePath: string
loc: SourcePositions

optional: 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

DocumentationNode

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

DocumentationNode

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

DocumentationNode

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

DocumentationNode

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

DocumentationNodeWithChildren

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

DocumentationNodeWithChildren

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

DocumentationNodeWithChildren

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

DocumentationNodeWithValue

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

DocumentationNodeWithChildren

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

DocumentationNodeWithChildren

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

DocumentationNodeWithChildren

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

DocumentationNodeWithValue

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

DocumentationNodeWithValue

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 |