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

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

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