@onerepo/plugin-docgen

Installation

Section titled Installation

npm

Install via npm

npm install --save-dev @onerepo/plugin-docgen

yarn

Install via Yarn

yarn add --dev @onerepo/plugin-docgen

pnpm

Install via pnpm

pnpm install --save-dev @onerepo/plugin-docgen

Example

Check out our very own source level example generated directly from the oneRepo source code using this plugin.

Configuration

Section titled Configuration

docgen()

Section titled docgen()

docgen(opts): Plugin

Include the eslint plugin in your oneRepo plugin setup:

onerepo.config.ts

import { docgen } from '@onerepo/plugin-docgen';

export default {
  plugins: [docgen()],
};

Parameters

Section titled Parameters

Parameter	Type
opts	Options

Options

Section titled Options

type Options: {
  format: "markdown" | "json";
  name: string | string[];
  outFile: string;
  outWorkspace: string;
  safeWrite: boolean;
};

Full configuration options for the Docgen core command.

onerepo.config.ts

import { docgen } from '@onerepo/plugin-docgen';

export default {
  plugins: [
    docgen({
      format: 'markdown',
      outFile: './docs/cli.md',
      safeWrite: true,
    }),
  ],
};

Type declaration

Section titled Type declaration

format?

Section titled format?

optional format: "markdown" | "json";

Default output format for the documentation

• Default: 'markdown'

name?

Section titled name?

optional name: string | string[];

Override the name of the command.

• Default: 'docgen'

outFile?

Section titled outFile?

optional outFile: string;

If set, a file will be written by default to the given location (in the given outWorkspace)

outWorkspace?

Section titled outWorkspace?

optional outWorkspace: string;

If outFile is also set, the generated documentation will be written out.

safeWrite?

Section titled safeWrite?

optional safeWrite: boolean;

Set to true to amend content to the given file using the file.writeSafe | file.writeSafe method.

Commands

Section titled Commands

one docgen

Section titled one docgen

Generate documentation for the oneRepo cli.

one docgen [options...]

Help documentation should always be easy to find. This command will help automate the creation of docs for this command-line interface. If you are reading this somewhere that is not your terminal, there is a very good chance that this command was already run for you!

Add this command to your one Repo tasks on pre-commit to ensure that your documentation is always up-to-date.

Option	Type	Description
--add	boolean	Add the output file to the git stage
--format	"markdown", "json", default: "markdown"	Output format for documentation
--heading-level	number	Heading level to start at for Markdown output
--out-file	string	File to write output to. If not provided, stdout will be used
--out-workspace	string	Workspace name to write the —out-file to
--safe-write	boolean	Write documentation to a portion of the file with start and end sentinels.

Advanced options

Option	Type	Description
--command	string	Start at the given command, skip the root and any others
--show-advanced	boolean	Pair with --help to show advanced options.
--use-defaults	boolean	Use the oneRepo default configuration. Helpful for generating default documentation.