Announcing Acquit 1.0.0: Generate Docs from Mocha Tests

After nearly 4 years, Acquit, the best tool for compiling Mocha tests into documentation on npm, is now at v1.0.0. I've found acquit to be indispensable over the last few years for keeping the Mongoose docs current, deploying internal API docs, as well as for writing ebooks. If you want to get started, check out the new Acquit website, or download Acquit on npm.

Getting Started With Acquit

Let's face it, maintaining documentation examples is a huge pain. When your API changes, you usually update your tests, but what about updating your docs? If you don't have automated checks in place to make sure your docs are correct, you get bug reports saying your examples are out of date. And if you're writing new content, you're stuck copy/pasting examples that you're not going to be able to find again. Acquit gives you a better way.

Acquit itself is just a parser that transforms raw Mocha test code parsed by esprima into a more productive format, including handling markdown in comments. In addition to the parser, Acquit has numerous plugins that let you combine your docs and test code in different ways.

The simplest plugin to get started with is acquit-markdown. This plugin takes in a Mocha test file and converts it into a Markdown file. Test descriptions become headers, leading comments above test descriptions become paragraphs, and test bodies become code samples. Suppose you have the below example.js file:

describe('foo', function() {
  /* This is how you print "Hello, World!" in JavaScript */
  it('bar', function() {
    console.log('Hello, World!');
  });

  // You can print any string
  it('baz', function() {
    console.log('Bye!');
  });
});

Running acquit-markdown from the command line will generate markdown from this file:

$ ./node_modules/.bin/acquit-markdown -p example.js
# foo

## It bar

This is how you print "Hello, World!" in JavaScript

```javascript
console.log('Hello, World!');
```

## It baz

You can print any string

```javascript
console.log('Bye!');
```

Mocha tests often come with boilerplate that you don't want to end up in your examples, like the done() function. Thankfully, there's an acquit-ignore plugin that tells Acquit to ignore code that's delimited by // acquit:ignore:start and // acquit:ignore:end.

describe('test', function() {
  // `setTimeout()` runs a function asynchronously
  it('async', function(done) {
    setTimeout(() => {
      console.log('This is async');
      // acquit:ignore:start
      done();
      // acquit:ignore:end
    }, 50);
  });
});

You can tell the acquit-markdown executable to pull in the acquit-ignore plugin using the -r flag:

$ ./node_modules/.bin/acquit-markdown -r acquit-ignore -p ./example.js
# test

## It async

`setTimeout()` runs a function asynchronously

```javascript
setTimeout(() => {
console.log('This is async');
}, 50);
```

Using Acquit For Existing Content

Another way to run Acquit is to use the acquit-require plugin. This plugin operates on a string and replaces instances of [require:foo] with the first test that matches the regular expression 'foo'.

For example, suppose you have the below sample.md file:

Printing "Hello, World" in JavaScript is easy:

```
[require:bar]
```

And a test file example.js:

describe('foo', function() {
  it('bar', function() {
    console.log('Hello, World!');
  });
});

You can use acquit-require to pull in the first test whose description matches 'bar'.

$ ./node_modules/.bin/acquit-require -p sample.md -t example.js
Printing "Hello, World" in JavaScript is easy:

```
console.log('Hello, World!');
```

You can also use acquit-require programmatically from Node.js.

Moving On

Acquit has become a key part of my workflow as a module maintainer, API developer, and writer. Acquit saves you time by letting you leverage existing test cases in your examples and ensures your examples stay up to date. Plus, documentation coverage becomes as easy as plugging in a test coverage library like nyc. Check out Acquit's new website and get serious about your docs!