{"id":15698948,"url":"https://github.com/samkirkland/knockout-component-documentor","last_synced_at":"2025-05-09T02:15:00.247Z","repository":{"id":34435757,"uuid":"81283358","full_name":"SamKirkland/Knockout-Component-Documentor","owner":"SamKirkland","description":"A Knockout.js component that generates documentation for your Knockout components","archived":false,"fork":false,"pushed_at":"2022-12-29T21:47:02.000Z","size":2975,"stargazers_count":6,"open_issues_count":19,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-09T02:14:53.483Z","etag":null,"topics":["component","documentation-generator","knockout","knockout-components","knockoutjs","webcomponents"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SamKirkland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-08T03:28:49.000Z","updated_at":"2022-12-08T23:50:42.000Z","dependencies_parsed_at":"2023-01-15T07:15:31.057Z","dependency_job_id":null,"html_url":"https://github.com/SamKirkland/Knockout-Component-Documentor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamKirkland%2FKnockout-Component-Documentor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamKirkland%2FKnockout-Component-Documentor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamKirkland%2FKnockout-Component-Documentor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamKirkland%2FKnockout-Component-Documentor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamKirkland","download_url":"https://codeload.github.com/SamKirkland/Knockout-Component-Documentor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253176444,"owners_count":21866143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","documentation-generator","knockout","knockout-components","knockoutjs","webcomponents"],"created_at":"2024-10-03T19:36:21.949Z","updated_at":"2025-05-09T02:15:00.226Z","avatar_url":"https://github.com/SamKirkland.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Knockout Component Documentor\n\n#### [Check out the DEMO!](https://samkirkland.com/labs/Knockout-Component-Documentor/example/example.html)\n\n\n### Description\nA Knockout.js component that generates documentation for your Knockout components.\n\nDrop 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.\n\n\n### Getting Started\n\n##### Step 1: Document each component\nDocument each component with the standard [jsDoc](http://usejsdoc.org/) 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.\n\n```javascript\n/**\n * @component jsdoc-sample-component\n * @tags [\"demo\", \"example\", \"tag\", \"test\"]\n * @description A quite wonderful component.\n * @category JSDoc Folder\n * @param {ko.observable(string)} obsString - A observable that is a string type\n * @param {string} [defaultString=default value] - This param has a default value of \"default value\"\n * @param {number} numParam - A param number type\n * @param {ko.observable(number)} obsNumber - A observable that is a number type\n */\n```\n\n##### Step 2: Run the NPM command\nRun the command `\"npm run document-components\"`. This command will look through your solutions jsdocs and generate a `jsdocs.json` file with your documented components.\n\n##### Step 3: Setup the NPM command to run on every build (optional)\nIt's a good idea to run the command in step 2 on every build so your component documentation is always up to date.\n\nYou can have webpack run this command by installing the NPM library `webpack-shell-plugin` and configuring it to run on each build\n\n```javascript\n// webpack.config.js\nconst WebpackShellPlugin = require('webpack-shell-plugin');\n\nmodule.exports = {\n\t// your config...\n\tplugins: [\n\t\tnew WebpackShellPlugin({\n\t\t\tonBuildEnd: ['npm run document-components']\n\t\t})\n\t],\n\t// your config...\n};\n\n```\n\n\n##### Step 4: Add the component to your page\nAdd the component js file in your page:\n```html\n\u003cscript src=\"knockout-component-documentor.bundle.js\"\u003e\u003c/script\u003e\n```\n\nPass the path of the generated file in step 2 into the `\u003cknockout-component-documentor\u003e` component. The default location of `jsdocs.json` is the same folder as `package.json`\n```html\n\u003cknockout-component-documentor params=\"jsdocs: { location: '../jsdocs.json' }\"\u003e\u003c/knockout-component-documentor\u003e\n```\n\n\n### Properties\nKnockout Component Documentor supports many properties, if the following properties aren't sufficient see the custom properties section.\n\n| Property      \t\t| Type          | Description                                           |\n|:---------------------:|:-------------:|:-----------------------------------------------------:|\n| description   \t\t| `string`      | A description of the component                        |\n| category (optional)\t| `string`      | Components with a category defined will appear within a submenu. Components with the same category (case sensitive) are grouped into the same submenu |\n| tags (optional)\t\t| `string[]`    | Displayed under the title and searchable in the navigation |\n| pages (optional)\t\t| `string[]`    | Displayed under the description, the strings should be valid links to the pages this component is used on. Useful for regression testing |\n\n\n### Custom Properties\nCustom properties are used when the built in jsDoc properties  above just aren't enough for your use case.\n\n```javascript\n/**\n * @component jsdoc-sample-component\n * @description A component with a custom param!!!\n * @myCustomParam You can have unlimited custom params\n * @anotherCustomParam Awesome!\n */\n```\n\n2. Then specify how you want them to be displayed by passing in innerHTML into the component.\n```html\n\u003cknockout-component-preview\u003e\n\t\u003c!-- ko if: myCustomParam --\u003e\n\t\tThis will only be displayed when a component sets the myCustomParam.\u003cbr\u003e\n\t\tmyCustomParam value: \u003cdiv data-bind=\"text: myCustomParam\"\u003e\u003c/div\u003e\n\t\u003c!-- /ko --\u003e\n\u003c/knockout-component-preview\u003e\n```\n\n\n### Supported Types\nThe following types are available for editing in jsdocs.\nThe editor will automatically pick the best editor for your parameter based on the type(s) you pass in.\n```javascript\n/**\n * @param {string} paramName - param description here\n * @param {boolean} paramName - param description here\n * @param {number} paramName - param description here\n * @param {object} paramName - param description here\n * @param {array} paramName - param description here\n * @param {function} paramName - param description here\n * @param {json} paramName - param description here\n * @param {date} paramName - param description here\n * @param {dateTime} paramName - param description here\n * @param {html} paramName - param description here\n * @param {innerHtml} paramName - param description here\n * @param {css} paramName - param description here\n */\n```\n\nIf you wan't to denote that these params are observable simply wrap them in `ko.observable(TYPE)`\n```javascript\n/**\n * @param {ko.observable(string)} paramName - param description here\n * @param {ko.observable(boolean)} paramName - param description here\n * and so on...\n */\n```\n\nAll unkown types will get a red \"Unsupported Type\" message within the offending component\n\n\n\n### Settings\nAll settings are optional. Pass the params into the component.\n\n| Property              | Type              | Default           | Description                                           |\n|:---------------------:|:-----------------:|:-----------------:|:-----------------------------------------------------:|\n| componentsToPreview   | `observableArray` | `[]`              | The ko.observableArray that will be updated with components being previewed |\n| documentSelf          | `boolean`         | `false`           | Should `\u003cknockout-component-preview\u003e` be included in the documentation output |\n| view                  | `string`          | `undefined`       | Determines which view to show onload, pass \"dynamicEdit\" or \"table\" |\n| includeFn             | `function`        | `function(componentName, filename, filepath)`    | A function used transform the component name into your include tags |\n| jsdocs                | `Object`          | `undefined`       | `jsdocs: { location: '../jsdocs.json', status: status }` |\n\n\n##### Example:\n```html\n\u003cknockout-component-preview params=\"\n\tincludeFn: function(componentName, filename, filepath){\n\t\treturn `\u003cscript src='/yourCustomFolder/${componentName}.js'\u003e\u003c/script\u003e`;\n\t}\n\"\u003e\n\u003c/knockout-component-preview\u003e\n```\n\n\n### Issues \u0026 Solutions\n\n##### Components are being documented\n1. Verify you completed all the `getting started` steps.\n2. Verify you added the `.js` files for all the component you want to document to your page\n3. 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\n4. If you're still having issues create a github issue\n\n##### No description provided\nThe description is a required parameter when documenting a component. To fix this add the `@description` jsdoc key to your component.\n```javascript\n/**\n * @component jsdoc-sample-component\n * @description A component with a description\n */\n```\n\n\n### Roadmap\n1. autoDocument option\n3. Support for defining examples\n4. NPM package\n5. React version\n\n\n### License\nCopyright Sam Kirkland\n\nReleased under The MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamkirkland%2Fknockout-component-documentor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamkirkland%2Fknockout-component-documentor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamkirkland%2Fknockout-component-documentor/lists"}