├── .gitignore ├── test ├── src │ ├── apidoc.json │ └── myapp.js ├── fixtures │ └── api_data.json └── index_test.js ├── .npmignore ├── README.md ├── LICENSE ├── package.json └── index.js /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | tmp/ 3 | npm-debug.log 4 | -------------------------------------------------------------------------------- /test/src/apidoc.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "best-app-ever", 3 | "version": "1.0.0" 4 | } 5 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | .git/ 2 | node_modules/ 3 | test/ 4 | .gitignore 5 | .npmignore 6 | npm-debug.log 7 | -------------------------------------------------------------------------------- /test/fixtures/api_data.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "type": "get", 4 | "url": "/do/something", 5 | "title": "", 6 | "test": "Test is replaced!", 7 | "foo": "Foo is replaced!", 8 | "priority": "Earlier is executed. New is executed. Later is executed.", 9 | "version": "0.0.0", 10 | "filename": "test/src/myapp.js", 11 | "group": "_home_rottmann_git_apidoc_plugin_test_test_src_myapp_js", 12 | "groupTitle": "_home_rottmann_git_apidoc_plugin_test_test_src_myapp_js", 13 | "name": "GetDoSomething" 14 | } 15 | ] 16 | -------------------------------------------------------------------------------- /test/src/myapp.js: -------------------------------------------------------------------------------- 1 | // This is an example app with apiDoc annotations. 2 | 3 | /** 4 | * @api {get} /do/something 5 | * @apiTest This content will be replaced via hook 'parser-find-elements' 6 | * @apiFoo This content will be replaced via hook 'parser-find-element-foo' 7 | * @apiPriority This content will be replaced 3 times 8 | * via hook 'parser-find-element-{name}' -> 'parser-find-element-apipriority' 9 | * With priority 40, 50 and 60. 10 | */ 11 | function doSomething() { 12 | console.log('best app ever'); 13 | } 14 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # apidoc-plugin-test 2 | 3 | __Only a test and example plugin. It demonstrates the usage of the apidoc hook system.__ 4 | 5 | apidoc search in global node modules dir and local `node_modules` for modules that start with `apidoc-plugin-`. (local installed plugins have higher priority) 6 | 7 | With a plugin you can add features like new parsers or filters and workers. 8 | 9 | A plugin can use apidoc-core [hooks](https://github.com/apidoc/apidoc-core/blob/master/hooks.md). 10 | Hooks can be used to extend or transform data. 11 | 12 | If you need a hook in apidoc-core please add your hook and provide a [pull request](https://github.com/apidoc/apidoc-core/). 13 | How to add a hook into apidoc-core view [source code](https://github.com/apidoc/apidoc-core/blob/20921efd32f95e7934333d633c56ff6f60722123/lib/parser.js#L454-L458). 14 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2013-2016 inveris OHG 2 | Author Peter Rottmann 3 | Licensed under the MIT license. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "apidoc-plugin-test", 3 | "version": "1.0.0", 4 | "description": "Only a test and example plugin. It demonstrates the usage of the apidoc hook system.", 5 | "author": "Peter Rottmann ", 6 | "license": { 7 | "type": "MIT", 8 | "url": "https://github.com/apidoc/apidoc/blob/master/LICENSE" 9 | }, 10 | "main": "index.js", 11 | "homepage": "http://apidocjs.com", 12 | "repository": { 13 | "type": "git", 14 | "url": "https://github.com/apidoc/apidoc-plugin-test.git" 15 | }, 16 | "scripts": { 17 | "test": "npm run jshint && mocha test/", 18 | "jshint": "jshint", 19 | "build-example": "cd .. && apidoc-plugin-test/node_modules/apidoc/bin/apidoc -i apidoc-plugin-test/test/src/ -o apidoc-plugin-test/tmp/ --debug --verbose && cd apidoc-plugin-test", 20 | "check-updates": "npm-check-updates" 21 | }, 22 | "keywords": [ 23 | "apidoc", 24 | "plugin", 25 | "apidoc-plugin" 26 | ], 27 | "engines": { 28 | "node": ">= 0.10.0" 29 | }, 30 | "devDependencies": { 31 | "apidoc": "*", 32 | "apidoc-core": "~0.7.0", 33 | "fs-extra": "^0.28.0", 34 | "jshint": "^2.9.2", 35 | "mocha": "^2.4.5", 36 | "npm-check-updates": "^2.6.3", 37 | "should": "^8.3.1" 38 | }, 39 | "jshintConfig": { 40 | "camelcase": true, 41 | "curly": false, 42 | "eqeqeq": true, 43 | "forin": true, 44 | "latedef": false, 45 | "newcap": true, 46 | "undef": true, 47 | "unused": true, 48 | "trailing": true, 49 | "node": true, 50 | "browser": true, 51 | "predef": [ 52 | "it", 53 | "describe", 54 | "before", 55 | "after" 56 | ] 57 | } 58 | } 59 | -------------------------------------------------------------------------------- /test/index_test.js: -------------------------------------------------------------------------------- 1 | /*jshint unused:false, expr:true */ 2 | 3 | /** 4 | * Test: apiDoc full parse 5 | */ 6 | 7 | // node modules 8 | var apidoc = require('apidoc-core'); 9 | var exec = require('child_process').exec; 10 | var fs = require('fs-extra'); 11 | var path = require('path'); 12 | var should = require('should'); 13 | 14 | describe('Create doc and compare with fixture', function() { 15 | 16 | var exampleBasePath = 'test'; 17 | var fixturePath = exampleBasePath + '/fixtures'; 18 | 19 | function log() { 20 | // can add an emitter here and capture it in the tests with chai-spies 21 | } 22 | 23 | var logger = { 24 | debug : log, 25 | verbose: log, 26 | info : log, 27 | warn : log, 28 | error : log, 29 | }; 30 | 31 | var api = {}; 32 | 33 | before(function(done) { 34 | fs.removeSync('./tmp/'); 35 | done(); 36 | }); 37 | 38 | after(function(done) { 39 | done(); 40 | }); 41 | 42 | // create 43 | it('should create an example in memory', function(done) { 44 | apidoc.setLogger(logger); 45 | apidoc.setGeneratorInfos({}); 46 | apidoc.setPackageInfos({ 47 | 'name': 'test', 48 | 'version': '0.0.0' 49 | }); 50 | 51 | api = apidoc.parse({ 52 | src: exampleBasePath + '/src/' 53 | }); 54 | 55 | if (api === false) 56 | throw new Error('Parse failed.'); 57 | 58 | done(); 59 | }); 60 | 61 | // compare 62 | it('created files should equal to fixtures', function(done) { 63 | var fixtureContent = fs.readFileSync(fixturePath + '/api_data.json', 'utf8'); 64 | var createdContent = api.data; 65 | 66 | var fixtureLines = fixtureContent.split(/\n/); 67 | var createdLines = createdContent.split(/\n/); 68 | createdLines.push(''); // Empty line at end. 69 | 70 | for (var lineNumber = 0; lineNumber < fixtureLines.length; lineNumber += 1) { 71 | if (fixtureLines[lineNumber] !== createdLines[lineNumber]) 72 | throw new Error('Generated file does not equals to fixture api_data.json in line ' + (lineNumber + 1) + 73 | '\nfixture: ' + fixtureLines[lineNumber] + 74 | '\ncreated: ' + createdLines[lineNumber] 75 | ); 76 | } 77 | 78 | done(); 79 | }); 80 | 81 | }); 82 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Only a test and example plugin. It demonstrates the usage of the apidoc hook system. 3 | * 4 | * Hook overview: https://github.com/apidoc/apidoc-core/hooks.md 5 | */ 6 | var app = {}; 7 | 8 | module.exports = { 9 | 10 | init: function(_app) { 11 | app = _app; 12 | 13 | // 14 | // Hooks 15 | // 16 | app.addHook('parser-find-elements', parserFindElements); 17 | app.addHook('parser-find-element-apifoo', parserFindElementApiFoo); 18 | 19 | // Hooks with priority 20 | // Default is 100, you should select intervals in 10 steps. 21 | 22 | // Priority is usefull to execute something before or after other plugins 23 | // or overwrite their behavior. 24 | 25 | // Example if 2 Plugins have the same priority: 26 | // Both have priority 50 so Old will be ignored and overwritten with New 27 | app.addHook('parser-find-element-apipriority', parserFindElementApiPriorityOld, 50); 28 | app.addHook('parser-find-element-apipriority', parserFindElementApiPriorityNew, 50); 29 | 30 | // Earlier will be executed first (priority 40) 31 | // then New (from above with prio 50) 32 | // and Later at last (60) 33 | app.addHook('parser-find-element-apipriority', parserFindElementApiPriorityLater, 60); 34 | app.addHook('parser-find-element-apipriority', parserFindElementApiPriorityEarlier, 40); 35 | 36 | // 37 | // Add Parsers (!!! experimental !!!) 38 | // 39 | app.parsers.apitest = { 40 | parse : parseTest, 41 | path : 'local', 42 | method : 'insert' 43 | }; 44 | app.parsers.apifoo = { 45 | parse : parseFoo, 46 | path : 'local', 47 | method : 'insert' 48 | }; 49 | app.parsers.apipriority = { 50 | parse : parsePriority, 51 | path : 'local', 52 | method : 'insert' 53 | }; 54 | } 55 | 56 | }; 57 | 58 | /** 59 | * Replace all current elements. 60 | */ 61 | function parserFindElements(elements, element, block, filename) { 62 | // Here you can do something with all elements 63 | if ( element.name === 'apitest' ) { 64 | // Remove last 65 | elements.pop(); 66 | 67 | // Do something. 68 | element.content = 'Test is replaced!'; 69 | 70 | // Add new 71 | elements.push(element); 72 | } 73 | return elements; 74 | } 75 | 76 | /** 77 | * A specific element. 78 | */ 79 | function parserFindElementApiFoo(element, block, filename) { 80 | // Here you can do something with one element 81 | element.content = 'Foo is replaced!'; 82 | return element; 83 | } 84 | 85 | /** 86 | * Old is never executed. 87 | */ 88 | function parserFindElementApiPriorityOld(element, block, filename) { 89 | element.content = 'Not executed cause parserFindElementPriorityNew overwrite it.'; 90 | return element; 91 | } 92 | 93 | /** 94 | * New will be executed. 95 | */ 96 | function parserFindElementApiPriorityNew(element, block, filename) { 97 | element.content = element.content + ' New is executed.'; 98 | return element; 99 | } 100 | 101 | /** 102 | * Earlier will be executed. 103 | */ 104 | function parserFindElementApiPriorityEarlier(element, block, filename) { 105 | element.content = 'Earlier is executed.'; 106 | return element; 107 | } 108 | 109 | /** 110 | * Later will be executed. 111 | */ 112 | function parserFindElementApiPriorityLater(element, block, filename) { 113 | element.content = element.content + ' Later is executed.'; 114 | return element; 115 | } 116 | 117 | /** 118 | * Simple parser. Add test to tree. 119 | * Examples: https://github.com/apidoc/apidoc-core/tree/master/lib/parsers 120 | */ 121 | function parseTest(content) { 122 | return { 123 | test: content 124 | }; 125 | } 126 | 127 | /** 128 | * Simple parser. Add foo to tree. 129 | * Examples: https://github.com/apidoc/apidoc-core/tree/master/lib/parsers 130 | */ 131 | function parseFoo(content) { 132 | return { 133 | foo: content 134 | }; 135 | } 136 | 137 | /** 138 | * Simple parser. Add priority to tree. 139 | * Examples: https://github.com/apidoc/apidoc-core/tree/master/lib/parsers 140 | */ 141 | function parsePriority(content) { 142 | return { 143 | priority: content 144 | }; 145 | } 146 | --------------------------------------------------------------------------------