@typescript-runtime-schema/generate-docs

Generate opinionated documentation from source files and/or provided content

Installation

Using npm:

npm install @typescript-runtime-schema/generate-docs

Using yarn:

yarn add @typescript-runtime-schema/generate-docs

How it works

It will compose the README according to the documentation index file. The index file describes the overall content of the README you wish to generate with either file references or symbols.

Index file

The index file describes the format of the README.md to produce. For every new line in the index file it may only either include a, relative to the index file, file path to another markdown file to inline in the output or a symbol.

Symbols

The index file supports a few symbols and if present will be automatically generated & added from the source files:

• PackageName
• Description
• Installation
• API
• CLI
• License

You can specify the heading level for the generated content by prefixing the heading level before the symbol, like so:

# PackageName

If you omit the heading level the heading will be entirely omitted in the output.

You can pass arguments to the symbols by declaring them space separated after the symbol, example:

Installation yarn <!-- Will only generate yarn installation instructions -->

For which arguments you can specify for each symbol, please see the specific symbol documentation below.

PackageName

The package name is generated based on the name of package in present in the package.json.

Description

The description is generated based on the name of package in present in the package.json.

Installation

The installation instructions are generated based on the package name in the package.json. It will output installation examples for both yarn & npm.

Arguments: yarn - Optional: Generate documentation for how to install with yarn. npm - Optional: Generate documentation for how to install with npm.

API

The API documentation is generated using typedoc into markdown using typescript-plugin-markdown. If the outputted markdown documentation only contains one file it will be inlined into markdown, otherwise each file will be moved to <indexFileDirectory>/API/

CLI

The CLI documentation is generated by parsing the cli package.json and executing the script with the --help command. If the script successfully exits it will use the output as the CLI documentation.

License

The License section is generated using the license field in the package.json or the passed in argument.

Arguments: {LICENSE_NAME} - Optional: The name of the license to include in the README.

CLI

generate-docs

generate-docs

  Automatically generate documentation for typescript packages 

Options

  --index-file-path string   Relative path to the index file from current       
                             working directory                                  
  --entry-file-path string   Relative path to the entry file from current       
                             working directory                                  
  --ts-config-path string    Relative path to the tsconfig.json file from       
                             current working directory                          
  -o, --output string        Specifies the location the documentation should be 
                             written to. If omitted the documentation will be   
                             written to stdout.                                 
  -h, --help

API

Index

Functions

• generateDocs

Functions

generateDocs

▸ generateDocs(options: { documentationIndexFilePath: string ; entryFile: string ; overwrite?: boolean ; tsConfigFile: string }): Promise<string>

Defined in lib/index.ts:33

beta

Parameters:

Name | Type | ------ | ------ | options | { documentationIndexFilePath: string ; entryFile: string ; overwrite?: boolean ; tsConfigFile: string } |

Returns: Promise<string>

License

MIT License Copyright (c) 2021 Simon Johansson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.