A Knockout.js component that generates documentation for your Knockout components.

Drop this component on a page and it will create a live preview and editor for every component you have registered on the page. The recommended use case for this is a internal only page where developers, QA, and shareholders can see all available UI components.

Document each component with the standard jsDoc spec. The only special property knockout-component-documentor needs is the @component property. This should be specify the name of the component you're documenting.

/**
 * @component jsdoc-sample-component
 * @tags ["demo", "example", "tag", "test"]
 * @description A quite wonderful component.
 * @category JSDoc Folder
 * @param {ko.observable(string)} obsString - A observable that is a string type
 * @param {string} [defaultString=default value] - This param has a default value of "default value"
 * @param {number} numParam - A param number type
 * @param {ko.observable(number)} obsNumber - A observable that is a number type
 */

Run the command "npm run document-components". This command will look through your solutions jsdocs and generate a jsdocs.json file with your documented components.

It's a good idea to run the command in step 2 on every build so your component documentation is always up to date.

You can have webpack run this command by installing the NPM library webpack-shell-plugin and configuring it to run on each build

// webpack.config.js
const WebpackShellPlugin = require('webpack-shell-plugin');

module.exports = {
	// your config...
	plugins: [
		new WebpackShellPlugin({
			onBuildEnd: ['npm run document-components']
		})
	],
	// your config...
};

Add the component js file in your page:

<script src="knockout-component-documentor.bundle.js"></script>

Pass the path of the generated file in step 2 into the <knockout-component-documentor> component. The default location of jsdocs.json is the same folder as package.json

<knockout-component-documentor params="jsdocs: { location: '../jsdocs.json' }"></knockout-component-documentor>

Knockout Component Documentor supports many properties, if the following properties aren't sufficient see the custom properties section.

Custom properties are used when the built in jsDoc properties above just aren't enough for your use case.

/**
 * @component jsdoc-sample-component
 * @description A component with a custom param!!!
 * @myCustomParam You can have unlimited custom params
 * @anotherCustomParam Awesome!
 */

2. Then specify how you want them to be displayed by passing in innerHTML into the component.

<knockout-component-preview>
	<!-- ko if: myCustomParam -->
		This will only be displayed when a component sets the myCustomParam.<br>
		myCustomParam value: <div data-bind="text: myCustomParam"></div>
	<!-- /ko -->
</knockout-component-preview>

The following types are available for editing in jsdocs. The editor will automatically pick the best editor for your parameter based on the type(s) you pass in.

/**
 * @param {string} paramName - param description here
 * @param {boolean} paramName - param description here
 * @param {number} paramName - param description here
 * @param {object} paramName - param description here
 * @param {array} paramName - param description here
 * @param {function} paramName - param description here
 * @param {json} paramName - param description here
 * @param {date} paramName - param description here
 * @param {dateTime} paramName - param description here
 * @param {html} paramName - param description here
 * @param {innerHtml} paramName - param description here
 * @param {css} paramName - param description here
 */

If you wan't to denote that these params are observable simply wrap them in ko.observable(TYPE)

/**
 * @param {ko.observable(string)} paramName - param description here
 * @param {ko.observable(boolean)} paramName - param description here
 * and so on...
 */

All unkown types will get a red "Unsupported Type" message within the offending component

All settings are optional. Pass the params into the component.

<knockout-component-preview params="
	includeFn: function(componentName, filename, filepath){
		return `<script src='/yourCustomFolder/${componentName}.js'></script>`;
	}
">
</knockout-component-preview>

1. Verify you completed all the getting started steps.
2. Verify you added the .js files for all the component you want to document to your page
3. Verify the generated jsdoc.json file has your components documentation in it - if the jsdoc.json file is empty, or jsdoc comments aren't appearing in the file verify the location of your comments is valid. They should appear directly before the viewModel: function(params) { line when registering components
4. If you're still having issues create a github issue

The description is a required parameter when documenting a component. To fix this add the @description jsdoc key to your component.

/**
 * @component jsdoc-sample-component
 * @description A component with a description
 */

1. autoDocument option
2. Support for defining examples
3. NPM package
4. React version

Copyright Sam Kirkland

Released under The MIT License.