@structured-types/api-docs
npm i @structured-types/api-docs

@structured-types/api-docs

Extract structured type information from javascript and typescript files

by ccontrols

3.46.11 (see all)License:MITTypeScript:Built-In
npm i @structured-types/api-docs
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 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

NameTypeValue
Table*number1
TableRow*number2
TableCell*number3
Heading*number4
Paragraph*number5
Text*number6
Bold*number7
Emphasis*number8
Link*number9
Code*number10
InlineCode*number11
Block*number12
Collapsible*number13

propsToDocumentation

async function

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

parameters

NameTypeDescription
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*DocumentationOptionspage generation options
returnsPromise<DocumentationNode[]>

DocumentationNode

interface

Base documentation node

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

properties

NameTypeDescription
kind*NodeKindDocumentation node kinds

DocumentationNodeWithChildren

interface

Documentation node with children

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

extends

DocumentationNode

properties

NameTypeDescription
children*DocumentationNode[]
kind*NodeKindDocumentation node kinds

DocumentationNodeWithValue

interface

Documentation node with a value

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

extends

DocumentationNode

properties

NameTypeDescription
value*string
kind*NodeKindDocumentation node kinds

apiDocsConfig

async function

Read the api-docs configuration file

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

parameters

NameTypeDescription
fileName*stringthe file that is being analyzed, will be used the starting folder to search for configuration files.
configFileNamestringpass 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
returnsPromise<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

NameTypeParentDefault
kind*TableNodeKind1
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

NameTypeParentDefault
kind*TableRowNodeKind2
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

NameTypeParentDefault
kind*TableCellNodeKind3
children*DocumentationNode[]DocumentationNodeWithChildren

getRepoPath

async function

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

parameters

NameTypeDescription
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*stringfile path to start the search for a package.json
returnsPromise<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

NameTypeParentDefault
kind*HeadingNodeKind4
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

NameTypeParentDefault
kind*ParagraphNodeKind5
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

NameTypeParentDefault
kind*TextNodeKind6
value*stringDocumentationNodeWithValue

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

NameTypeParentDefault
kind*BoldNodeKind7
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

NameTypeParentDefault
kind*EmphasisNodeKind8
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

NameTypeParentDefault
kind*LinkNodeKind9
urlstring
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

NameTypeParentDefault
kind*CodeNodeKind10
value*stringDocumentationNodeWithValue

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

NameTypeParentDefault
kind*InlineCodeNodeKind11
value*stringDocumentationNodeWithValue

DocumentationOptions

type

Document page generation options

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

properties

NameTypeDescription
collapsedstring[]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.
extensionsstring[]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.
visiblestring[]List of type names, that should be "visible". This will limit which of the parsed props to be documented.
columnsColumnName[] | 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
sectionsSectionName[] | 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
skipInheritedbooleanWhether 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

Downloads/wk

2

GitHub Stars

33

LAST COMMIT

3mos ago

MAINTAINERS

1

CONTRIBUTORS

1

OPEN ISSUES

3

OPEN PRs

1
VersionTagPublished
3.46.11
latest
1mo ago
No alternatives found
No tutorials found
Add a tutorial