@scalvert/readme-api-generator NPM

@scalvert/readme-api-generator

Generates API documentation for your README, converting JSDoc to Markdown.

Installation

With npm:

npm install @scalvert/readme-api-generator --save-dev

With yarn:

yarn add @scalvert/readme-api-generator --dev

Usage

The readme-api-generator CLI uses jsdoc-to-markdown combined with HTML comment tokens in your README.md file to generate your API documentation. Follow these steps to set it up.

Add tokens to your README.md
Add  and  HTML comments where you'd like your content to be generated.
```
Some text before the docs.




Some text after the docs.
```
:warning: All content in between these tags will be replaced!
Add a script to your package.json that points to the files you want to include in your API documentation.
Using files:
```
"scripts": {
 "docs:generate": "readme-api-generator foo.js bar.js"
},
```
Using a directory:
```
"scripts": {
 "docs:generate": "readme-api-generator lib"
},
```
For projects using TypeScript, you can either ensure your TS files are built before generating the docuemntation. The file/directory input should be from your outDir.
```
"scripts": {
 "docs:generate": "npm run build && readme-api-generator <files list or directory>"
},
```
Or you can generate the markdown from the TypeScript files directly.
Then add the following to your package.json, where src is the path your TypeScript files are in:
```
"scripts": {
 "docs:generate": "readme-api-generator ./src --ts"
},
```
Write your jsdocs!

API

Functions

getFiles(filesOrDirectory) ⇒

Gets a list of files to be used to generate the Markdown content.

Kind: global function Returns: A list of files to be used to generate the markdown.

Param	Type	Description
filesOrDirectory	Array.<string>	The list of files or directory to read.

getReadme(workingDir) ⇒

Gets and reads the contents of the README.md file.

Kind: global function Returns: A tuple containing the readme file path and content.

Param	Type	Description
workingDir	string	The current working directory.

generateMarkdown(files) ⇒

Generates the markdown content from the supplied files.

Kind: global function Returns: The rendered markdown.

Param	Type	Description
files	Array.<string>	The list of files to generate the markdown content.

writeDocs(readmePath, readmeContent, docsContent)

Writes the markdown content into the README.md using the supplied placeholders as a marker to position the content.

Kind: global function

Param	Type	Description
readmePath	string	The path to the README.md file.
readmeContent	string	The content read from the README.md file.
docsContent	string	The generated markdown to be written to the README.md file.