@structured-types/api-docs v3.46.12

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

propsToDocumentation

async function

defined in @structured-types/api-docs/packages/api-docs/src/props-to-nodes.ts

parameters

DocumentationNode

interface

Base documentation node

defined in @structured-types/api-docs/packages/api-docs/src/types.ts

properties

DocumentationNodeWithChildren

interface

Documentation node with children

defined in @structured-types/api-docs/packages/api-docs/src/types.ts

extends

DocumentationNode

properties

DocumentationNodeWithValue

interface

Documentation node with a value

defined in @structured-types/api-docs/packages/api-docs/src/types.ts

extends

DocumentationNode

properties

apiDocsConfig

async function

Read the api-docs configuration file

defined in @structured-types/api-docs/packages/api-docs/src/index.ts

parameters

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

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

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

getRepoPath

async function

defined in @structured-types/api-docs/packages/api-docs/src/package-info/package-info.ts

parameters

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

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

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

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

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

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

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

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

DocumentationOptions

type

Document page generation options

defined in @structured-types/api-docs/packages/api-docs/src/types.ts

properties