thought

thought

A customizable documentation generator for github projects

Thought is still in development. It might be worth looking at it already, but I'm still trying to document my own projects with it, so the default templates will change as I go along. It's not ready for production use at the moment.

Overview / Motivation

The goal of Thought is making the documentation just as easy as thinking about it.

Are you sometimes annoyed about documentation that does represent the current state of the project? Like example-snippets that don't work or have a different output when you actually run them?

Most of the time, the problem is, that the documentation lives too far away from the code. The API-reference is up-to-date most of the time, because it is actually maintained next to the code. But what about the rest?

With Thought, you can assemble documentation from a variety of places. You can include API-docs into your README, you can include example and actuall run them to include the output. You can include the command line reference by calling the main program with a --help parameter.

When your examples throw errors, you will notice that. When you make changes to your code, the example output in your documentation will change as well!

Generating a simple README.md just requires executing thought in your project directories. Thought will run your package.json through a Handlebars template with a list of registered partials in order to do that.

Since that is mostly not exactly what you want, it is possible to override each of the partials with your own and to create more templates each of which will result in one markdown-file in your repo.

Thought offers a small list of simple helpers to

• parse jsdoc-comments (not only in javascript-files but in many languages) and include them at any location in your documenation files.
• include any file
• include javascript example files (replacing require of the main module by the module name)
• run example files or any program and include the output

I have taken a lot of inspiration form verb by Jon Schlinkert, but I wanted something simpler. There are other simple README-generators out there that you can't adapt, so the idea of using package.json to generate a README.md is not new.

Installation

npm install -g thought

Usage

The simplest usage is just to run thought run from your project root directory. In the default configuration, this will generate a README.md from the information in the package.json.

Consider the following example

example-project/
├── CONTRIBUTING.md
├── LICENSE.md
├── examples/
│   └── example.js
├── index.js
└── package.json

and have a look at the files index.js, examples/example.js and examples/example.js, LICENSE.md, package.json

Thought will render information from package.json, include the examples/examples.js, execute the examples/example.js file and include the process-output and reference the LICENSE.md.

The resulting README.md can be viewed here

CLI options

Calling thought --help will print a command-line reference:

Usage: thought [options] [command]


  Commands:

    run [options]   Generate documentation from your package.json and some templates.
    init            Register scripts in the curent module's package.json
    check-engines   Check that all engines (such as npm) have versions that ensure Thought to run correctly

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -d, --debug    higher stack-trace-limit, long stack-traces

Calling thought from node.

var thought = require('thought')

thought({
  cwd: 'example-project'
})

Using thought as version-script for npm

npm supports a version script from version 2.13.0 on. This script is called when invoking npm version ... after bumping the version number but prior to commiting the change.

Using thought init you can install scripts for version and preversion in your package.json that will run thought run -a on every version bump. This will include the updated documenation in the same commit that contains the version bump. Furthermore, if you (or any other contributor of your module) is using npm prior to version 2.13.0. The preversion-script will fail.

This is especially helpful when using the helper withPackageOf to include links to files in your github repository (since these links include the version tag on github).

API-reference

thought(options)

Execute Thought in the current directory

Kind: global function
Api: public

Param	Type	Description
options	object
options.cwd	string	the working directory to use as project root

License

thought is published under the MIT-license. See LICENSE.md for details.

Release-Notes

For release notes, see the changelog

Contributing guidelines

See CONTRIBUTING.md.

Changelog

v0.3.0 - 2015-08-15

Change

• Generate CONTRIBUTING.md instead of including guidelines into README (https://github.com/blog/1184-contributing-guidelines)

Fix

• htmlId helper now always returns lowercase