Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nknapp/thought
A customizable documentation generator for github projects
https://github.com/nknapp/thought
Last synced: 13 days ago
JSON representation
A customizable documentation generator for github projects
- Host: GitHub
- URL: https://github.com/nknapp/thought
- Owner: nknapp
- License: mit
- Created: 2015-06-29T20:27:32.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-07-16T23:10:50.000Z (4 months ago)
- Last Synced: 2024-10-06T03:41:50.312Z (about 1 month ago)
- Language: JavaScript
- Homepage: https://nknapp.github.io/thought
- Size: 1.1 MB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# thought
[](https://npmjs.com/package/thought)
[](https://github.com/nknapp/thought/actions/workflows/ci.yml)
[](https://greenkeeper.io/)
> 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](https://npmjs.com/package/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](docs/helpers.md) 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](https://npmjs.com/package/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
```bash
npm -g install thought
thought run -a
```
> **Warning: Thought does not work correctly in Windows machines, because of the separator
> "\\" instead of "/"
> If you want to fix that, please contact me.**
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](docs/example-project-1-simple.md) shows the generated documentation for
a very simple, newly generated npm-package.
* [The second example-project](docs/example-project-2-example-license-jsdoc-badges.md)
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](docs/example-project-3-templates-partials-helpers-preprocessor.md) 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](docs/example-project-4-writing-plugins.md) 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 display help for command
Commands:
run [options] Generate documentation from your package.json
and some templates.
init Register scripts in the current module's
package.json
eject [prefix] [filename] Extract part of thought's default templates into
the local configuration directory
up-to-date Perform up-to-date check of the current
documentation. Exit with non-zero exit-code when
thought must be run again.
help [command] display help for command
```
#### `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](https://npmjs.com/package/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
```json
// 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.
```js
const 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](docs/helpers.md)
# License
`thought` is published under the MIT-license.
See [LICENSE.md](LICENSE.md) for details.
# Release-Notes
For release notes, see [CHANGELOG.md](CHANGELOG.md)
# Contributing guidelines
See [CONTRIBUTING.md](CONTRIBUTING.md).