npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@structured-types/api-docs

v3.46.12

Published

Create api documentation nodes using structured-types/api

Downloads

51

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

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