thought

thought

A customizable documentation generator for github projects

Every npm-package should have a README-file that contains a short description of what it is and what it does, an explanation of how to install it, one or more usage examples and an API-reference for all functions, parameters and options.

Thought helps you create such a README without a lot of hassle.

Easy startup: Thought uses handlebars with a default set of templates, partials and helpers to create a README.md- and a CONTRIBUTING.md-file. The input of the template is mainly the package.json-file of your project. Just run thought run -a in your project folder.

Examples that actually work: The file examples/example.js is included into the README by default. You can use require('../') to reference your package and thus build examples that are executable and testable. When you run thought run -a, the ../ will be replaced by the name of your package. The example will be run and the output will be included as well.

Fully customizable: You can change every template, partials and helper if you need to. And since you are writing Handlebars-templates, you can use helpers like {{npm 'lodash}} to create a link to a package's npm-page and {{dirTree '.thought' 'snippets/**'}} to generate directory-trees.

Plugins: You can write plugins that bundle your customizations. You can write a thought-plugin-my-name-base that contains all the customizations that you need in your module. Or you can bundle certain functionalities, like the thought-plugin-jsdoc and share them on npm.

Basic Usage

Starting with version 2.0, Thought will support NodeJS LTS and active versions. Dropping support for pre-LTS versions will not be considered a breaking change.

The most basic way to use Thought is to go into your directory of your package.json and type

npm -g install thought
thought run -a

Thought will then create the files README.md and CONTRIBUTING.md with reasonable default texts for Open-Source projects in JavaScript that are hosted on http://npmjs.com.

Examples

Thought can be used just as-is or in a more sophisticated fashion. The more work you put in, the better the documentation that comes out. The following example show the different levels of details:

• The first example shows the generated documentation for a very simple, newly generated npm-package.
• The second example-project demonstrates the following features:
  • an example program in the README
  • a link to a LICENSE-file
  • a JSDoc-Reference of the main file
  • badges for npm, travis, coveralls and greenkeeper
• The third example-project shows how to
  • override contents with custom content (using custom partials and custom templates)
  • create new files by adding templates
  • add custom helpers that can be called from within templates and partials
  • add a custom preprocessor to modify the input data (i.e. the package.json and the configuration)
• The fourth example-project demonstrates how to bundle customizations into a plugin that can be reused and published on npm.
• The (probably) largest example is Thought itself. All the documentation is generated by Thought. In fact, some of the features like the ignore-option of the {{dirTree}}-helper were added in order to generate the documentation properly. Have a look at the .thought-directory and learn what is possible.

CLI options

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

Usage: thought [options] [command]

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

Commands:
  run [options]  Generate documentation from your package.json and some templates.
  init           Register scripts in the current module's package.json
  check-engines  Check that all engines (such as npm) have versions that ensure Thought to run correctly
  up-to-date     Perform up-to-date check of the current documentation. Exit with non-zero exit-code when thought must be run again.

thought init: Using Thought as version-script for npm

thought init will install thought run -a as version script in your package.json. This will run thought every time you bump the package-version using npm version. The updated documenation will be commited along with the version bump.

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

thought up-to-date: Using Thought as pre-push hook.

Along with the library husky, Thought can be used as pre-push hook to prevent missing README updates. When you change things that would otherwise update the documentation (like an example), it can easily happen that you push those changes without running Thought first.

You can prevent this from happening by using husky and a prepush script

// Edit package.json
{
  "scripts": {
    "prepush": "thought up-to-date"
  }
}

The command thought up-to-date runs Thought without writing any files, but it checks if any of the files that would have been written, would have been changed by the write. If this is the case, it exits with a non-zero exit-code and prints an error message.

Attention: This will not work properly if the output of examples includes variable parts such as the current timestamp or local wheather conditions

Calling thought from node.

var thought = require('thought')

thought({
  addToGit: true
})

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 (deprecated because it does not always work as expected)
[options.addToGit]	boolean	add created files to git

Builtin Handlebars-helpers

The documentation for the builtin-helpers can be found here

License

thought is published under the MIT-license.

See LICENSE.md for details.

Release-Notes

For release notes, see CHANGELOG.md

Contributing guidelines

See CONTRIBUTING.md.

Changelog

Version 2.0.0 (Wed, 20 Feb 2019 22:02:31 GMT)

• BREAKING CHANGES

  • b437746 auto-drop support for unsupported versions NodeJS - Nils Knappmeier (BREAKING CHANGE): In the future, only supported versions (LTS and active) of NodeJS will be supported by this package.
  • 15ed4b6 feat: remove greenkeeper autodetection in hasGreenkeeper-helper - Nils Knappmeier The Greenkeeper badge now has to be configured in .thought/config.js

• refactorings

  • 043ff2a refactor: use promise-based fs-extra instead of pify(fs()) - Nils Knappmeier
  • a0011fd refactor: remove obsolete packages - Nils Knappmeier
  • a84fdd9 fix: remove implicit use of Q - Nils Knappmeier
  • b19ea37 chore: remove unneeded devDependency "recursive-copy" - Nils Knappmeier
  • 02760c5 refactor: replace 'm-io' by 'fs-extra' and 'glob' - Nils Knappmeier
  • 22e58cc chore: bump dependency versions, use nyc instead of istanbul - Nils Knappmeier

• bump dependency versions

  • c3eac5d, 22e58cc, f44963f, 4a4702f, f44963f 11734aa

• bugfixes

  • def3693 fix: fix silently rejected promise warning in dirTree helper - Nils Knappmeier
  • 003e932 fix: handle missing plugins properly in config - Nils Knappmeier