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

1. Add tokens to your README.md

   Add <!--DOCS_START--> and <!--DOCS_END--> HTML comments where you'd like your content to be generated.

   Some text before the docs.
   
   <!--DOCS_START-->
   <!--DOCS_END-->
   
   Some text after the docs.

   :warning: All content in between these tags will be replaced!

2. 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"
   },

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

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT