@structured-types/api-docs

v3.46.12

Published

2 years ago

Create api documentation nodes using structured-types/api

Downloads

0High
0Medium
0Low

atanasster

jsdoc javascript documentation

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.

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]: interfacekind: 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.RegExname: stringalias: stringparentname*: stringloc: SourceLocationlocfilePath: stringloc: SourcePositionsoptional: booleanreadonly: booleanabstract: booleanasync: booleanvisibility: "private" | "protected" | "public"static: booleantype: stringextension: stringdescription: stringfires: string[]see: string[]examples: JSDocExample[]tags: JSDocPropTag[]summary: stringdeprecated: string | trueignore: booleanusage: 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 | ConfigOptionsfsfileExists*: function (filePath*: ) => Promise<boolean>readDirectory*: function (path*: ) => Promise<string[]>isDirectory*: function (path*: ) => Promise<boolean>readFile*: function (filePath*: ) => Promise<(string, null)>cwd*: function () => stringelementId: stringcosmic: 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* | STFSfileExists*: 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 | SourceLocationfilePath: stringlocstart*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 | STFSfileExists*: 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 |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

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