Client
Now that you've compiled a sweet data file packed with documentation goodness, what next?
Well, you've got some options. This package does not provide the tools to render the data, but they're fairly easy to construct once you understand the data format. The @documentalist/client package provides functions, interfaces, and type guards for working with the output of the compiler.
Compiler
Register plugins with .use(pattern, plugin). Supply a pattern to match files against; matched files will be compiled by the plugin. Documentation data will be collected into a single blob and can be easily written to a file or fed into another tool.
const { Documentalist, MarkdownPlugin, TypescriptPlugin } = require("@documentalist/compiler");
const { writeFileSync } = require("fs");
new Documentalist()
.use(".md", new MarkdownPlugin())
.use(/\.tsx?$/, new TypescriptPlugin({ excludeNames: [/I.+State$/] }))
.documentGlobs("src/**/*") // ← async operation, returns a Promise
.then(docs => JSON.stringify(docs, null, 2))
.then(json => writeFileSync("docs.json", json))
class Documentalist #
Exported from: @documentalist/compiler
Constructor
Methods
static create
|
Construct a new Documentalist instance with the provided options.
This method lends itself particularly well to the chaining syntax:
Documentalist.create(options).use(...).
|
clearPlugins
|
Returns a new instance of Documentalist with no plugins.
|
documentFiles
|
(files: IFile[]) => Promise<T>
Iterates over all plugins, passing all matching files to each in turn.
The output of each plugin is merged to produce the resulting
documentation object.
The return type T is a union of each plugin's data type.
|
documentGlobs
|
(...filesGlobs: string[]) => Promise<T>
Finds all files matching the provided variadic glob expressions and then
runs documentFiles with them, emitting all the documentation data.
|
use
|
Adds the plugin to Documentalist. Returns a new instance of Documentalist
with a template type that includes the data from the plugin. This way the
documentFiles and documentGlobs methods will return an object that is
already typed to include each plugin's output.
The plugin is applied to all files whose absolute path matches the
supplied pattern.
|
CLI
On the command line, the Markdown and Typescript plugins are enabled by default.
The CSS plugin can be enabled with --css. Plugins can be disabled with the no- prefix.
Options are not supported via the command line interface :sob:.
documentalist "src/**/*" --css --no-ts > docs.json
Plugins
Documentalist uses a plugin architecture to support arbitrary file types.
Use your own plugins by passing them to dm.use(pattern, plugin) with a
pattern to match against source files. The collected matched files will
be passed to your plugin's compile function, along with a compiler
instance that can be used to render blocks of markdown text.
interface IPlugin #
Exported from: @documentalist/clientA Documentalist plugin is an object with a compile(files, compiler) function
that returns a data object (or a promise for that object).
A common pattern is to define a class that implements this interface and use the constructor
to accept options.
import { ICompiler, IFile, IPlugin } from "documentalist/client";
export interface MyData {
pluginName: { ... }
}
export interface MyOptions {
...
}
export class MyPlugin implements IPlugin<MyData> {
public constructor(options: MyOptions = {}) {}
public compile(files: IFile[], compiler: ICompiler) {
return files.map(transformToMyData);
}
}
Methods
Overview
A sort-of-static site generator optimized for living documentation of software projects.
Documentalism 101
Documentalism is a two-step process:
- Get the data.
- Render the data.
The Documentalist compiler is an extensible solution to step 1: it helps you get all your data in one place, in a consistent format.
Configure Documentalist with plugins to extract documentation data from source files, then feed it a glob of files
and await your magical blob of documentation data!
Packages
This project contains multiple NPM packages:
License
This project is made available under the Apache-2.0 License.