@structured-types/api-readme
v3.46.12
Published
API documentation extractor for Readme.md files
Downloads
49
Readme
Table of contents
Overview
Markdown documentation generator/enhancer for javascript, typescript and react typescript projects. Can be used to generate API sections in your README.md files.
Installation
yarn add @structured-types/api-readme --dev
Markdown
API docs section
In your README.md
(or another markdown file) file, you will insert a <api-readme />
tag to generate the API section:
<api-readme />
Table of contents
In your README.md
(or another markdown file) file, you can insert a # Table of contents
header and it will be automatically filled with an extracted table of contents
Configuration
The configuration file options are documented in @structured-types/api-docs
DocumentOptions
You can configure api-readme either directly in your markdown file with inline configuration or with an external file.
Inline configuration
files
: a comma-separated list of the files to include in the documentation
<api-readme files="./src/index.ts"/>
id
: a string that should be linked to an element with options in the configuration file.
<api-readme id="my-section"/>
extract
: a comma-separated list of API names to extract. By default, all the exports will be documented.
<api-readme extract="parse, ParseOptions" files="./src/index.ts"/>
visible
: a comma-separated list of the properties to be visible. By default, all the extracted properties will be visible.
<api-readme visible="ParseOptions" files="./src/index.ts"/>
collapsed
: a comma-separated 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.
<api-readme collapsed="React.ReactNode"/>
extensions
: a comma-separated 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.
<api-readme extensions="react"/>
sections
: a comma-separated list of the sections to generateprops
|description
|examples
|title
|location
|all
. By default, all sections are generated.
<api-readme sections="description,props"/>
columns
: a comma-separated list of the columns in the property tablesname
|type
|parents
|value
|description
|all
. By default, all columns will be visible.
<api-readme columns="name,type,value,description"/>
collectHelpers
: boolean, to specify whether to document also helper props (parents, inherited, etc) or just the main extracted exports. By default, the helper props will be excluded from your documentation.
<api-readme files="./src/index.ts" collectHelpers=true/>
skipInherited
: boolean, to specify whether to skip properties that are "inherited", or "composed". For example,type OwnProps = { x: number } & React.LineProps
will only output thex
property and skip the inherited React library properties.
<api-readme files="./src/index.ts" skipInherited=true/>
maxDepth
: number, how deep to parse child props. By default, this is set to 6.
<api-readme files="./src/index.ts" maxDepth=10/>
- other options from the @structured-types/api package.
Configuration file
The configuration file options are documented in @structured-types/api-docs
Multiple elements
You can have multiple elements configured within the same configuration file.
For example, you have two components to document LineChart
and RadarChart
:
You can custom specify the element ids in README.md
<api-readme id="linechart">
...
<api-readme id="radarchart">
In your configuration file, you can specify distinct options for each element. The per-element options will be merged with the global options.
Javascript
module.exports = {
sections: ['props'],
elements: {
linechart: {
files: ['./src/charts/line/Chart.tsx'],
visible: ['LineChart'],
},
radarchart: {
files: ['./src/charts/radar/Chart.tsx'],
visible: ['RadarChart'],
}
}
};
JSON
module.exports = {
"sections": ["props"],
"elements": {
"linechart": {
"files": ["./src/charts/line/Chart.tsx"],
"visible": ["LineChart"]
},
"radarchart": {
"files": ["./src/charts/radar/Chart.tsx"],
"visible": ["RadarChart"]
}
}
};
YAML:
sections:
- props
elements:
linechart:
files:
- ./src/charts/line/Chart.tsx
visible:
- LineChart
radarchart:
files:
- ./src/charts/radar/Chart.tsx
visible:
- RadarChart
Launch
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.
...
"scripts": {
"docs": "api-readme",
...
},
...
Command-line options
-t
or--toc
: boolean (default:true
). Whether to generate a table of contents in your markdown file. You will need to create the section title such as# Table of contents
andapi-readme
will generate the content within this section.
yarn(npm) run api-readme -t=false
-f
or--file
: string (default:MARKDOWN.md
). The name of the markdown file to be processed. Make sure you have inserted a<api-readme />
tag within this file.
yarn(npm) run api-readme -f=./src/test.md
-c
or--config
: string. The api-docs configuration file full path and name.
yarn(npm) run api-readme -f=./src/test.md
-l
or--log
: boolean (default:true
). Display/or not the running logs.
yarn(npm) run api-readme -l=false