forked from angular/dgeni-packages
-
Notifications
You must be signed in to change notification settings - Fork 0
/
package.json
137 lines (137 loc) · 14.4 KB
/
package.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
{
"name": "dgeni-packages",
"version": "0.10.3",
"description": "A collection of dgeni packages for generating documentation from source code",
"scripts": {
"test": "jasmine-node .",
"cover": "istanbul cover jasmine-node -- ."
},
"repository": {
"type": "git",
"url": "https://github.com/angular/dgeni-packages.git"
},
"keywords": [
"ngdoc",
"angular",
"angularjs",
"dgeni",
"document generation",
"javascript",
"jsdoc"
],
"author": {
"name": "Pete Bacon Darwin"
},
"licenses": [
{
"type": "Apache",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
],
"bugs": {
"url": "https://github.com/angular/dgeni-packages/issues"
},
"peerDependencies": {
"dgeni": "^0.4.0"
},
"dependencies": {
"canonical-path": "0.0.2",
"catharsis": "^0.7.0",
"change-case": "^2.1.0",
"dgeni": "^0.4.0",
"esprima": "^1.0.4",
"estraverse": "^1.5.1",
"glob": "~3.2.8",
"htmlparser2": "^3.7.3",
"lodash": "~2.4.1",
"marked": "^0.3.2",
"minimatch": "^0.3.0",
"node-html-encoder": "0.0.2",
"nunjucks": "~1.0.1",
"q": "~1.0.0",
"q-io": "~1.10.9",
"stringmap": "^0.2.2",
"winston": "~0.7.2"
},
"devDependencies": {
"istanbul": "^0.2.7",
"jasmine-node": "^2.0.0",
"rewire": "~2.0.0"
},
"contributors": [
{
"name": "Peter Bacon Darwin",
"email": "pete@bacondarwin.com"
},
{
"name": "Stéphane Reynaud",
"email": "forresst@voila.fr"
},
{
"name": "Andy Joslin",
"email": "andytjoslin@gmail.com"
},
{
"name": "Pascal Precht",
"email": "pascal.precht@googlemail.com"
},
{
"name": "Julie",
"email": "ju.ralph@gmail.com"
},
{
"name": "Jim Cummins",
"email": "jim.for.cy@gmail.com"
},
{
"name": "Andrew Joslin",
"email": "andytjoslin@gmail.com"
},
{
"name": "thorn0",
"email": "thorn.mailbox@gmail.com"
},
{
"name": "kevinrowe",
"email": "kevinrowe@outlook.com"
},
{
"name": "Pete Bacon Darwin",
"email": "pete@bacondarwin.com"
},
{
"name": "Matthew Harris",
"email": "ftmomatt@gmail.com"
},
{
"name": "Konstantinos Rousis",
"email": "rousisk@gmail.com"
},
{
"name": "Tobias Bosch",
"email": "tbosch1009@gmail.com"
},
{
"name": "Thor Jacobsen",
"email": "freak.tm@gmail.com"
},
{
"email": "thorn.mailbox@gmail.com"
},
{
"name": "Lucas Galfaso",
"email": "lgalfaso@gmail.com"
},
{
"name": "Tim Kendrick",
"email": "timkendrick@gmail.com"
}
],
"readme": "# Dgeni Packages\n\nThis repository contains a collection of Dgeni **Packages** that can be used by the Dgeni documentation\ngenerator to create documentation from source code.\n\n\nOut of the box there are the following packages:\n\n* base - The minimal set of processors to get started with Dgeni\n* jsdoc - Tag parsing and extracting\n* nunjucks - The nunjucks template rendering engine. No longer in jsdoc - you must add this\n explicitly to your config or you will get\n `Error: No provider for \"templateEngine\"! (Resolving: templateEngine)`\n* ngdoc - The angular.js specific tag-defs, processors and templates. This loads the jsdoc and\n nunjucks packages for you.\n* examples - Processors to support the runnable examples feature in the angular.js docs site.\n* dgeni - Support for documenting Dgeni packages (**incomplete**)\n\n## `base` Package\n\n### Processors\n\n* `computeIdsProcessor` - Computes the `id` and `aliases` for documents using templates or helper\nfunctions, on a per docType basis.\n* `computePathsProcessor` - Computes the `path` and `outputPath` for documents using templates or helper\nfunctions, on a per docType basis.\n* `debugDumpProcessor` - dump the current state of the docs array to a file (disabled by default)\n* `readFilesProcessor` - used to load up documents from files. This processor can be configured to use a\nset of **file readers**. There are file readers in the `jsdoc` and `ngdoc` packages.\n* `renderDocsProcessor` - render the documents into a property (`doc.renderedContent`) using a\n`templateEngine`, which must be provided separately - see `nunjucks` package.\n* `unescapeCommentsProcessor` - unescape comment markers that would break the jsdoc comment style,\ne.g. `*/`\n* `writeFilesProcessor` - write the docs that have an `outputPath` to disk\n\n### Services\n\n* `aliasMap` - A map of ids/aliases to docs. This is used for matching references to documents in\nlinks and relations such as modules and object members.\n* `createDocMessage` - a helper for creating nice messages about documents (useful in logging and\nerrors)\n* `encodeDocBlock` - convert a block of code into HTML\n* `templateFinder` - search folders using patterns to find a template that matches a given document.\n* `trimIndentation` - \"intelligently\" trim whitespace indentation from the start of each line of a block\nof text.\n* `writeFile` - Write some contents to a file, ensuring the path to the file exists.\n\n\n#### Template Finding\n\nThe template used to render a doc is computed by the `templateFinder`, which uses the first match\nfrom a set of patterns in a set of folders, provided in the configuration. This allows a lot of control to provide\ngeneric templates for most situations and specific templates for exceptional cases.\n\nHere is an example of some standard template patterns:\n\n```js\ntemplateFinder.templatePatterns = [\n '${ doc.template }',\n '${doc.area}/${ doc.id }.${ doc.docType }.template.html',\n '${doc.area}/${ doc.id }.template.html',\n '${doc.area}/${ doc.docType }.template.html',\n '${ doc.id }.${ doc.docType }.template.html',\n '${ doc.id }.template.html',\n '${ doc.docType }.template.html'\n]\n```\n\n\n## `nunjucks` Package\n\nThis package provides a nunjucks driven implementation of the `templateEngine` required by the\n`base` package `renderDocsPocessor`. The \"nunjucks\" JavaScript template tool-kit to generates HTML\nbased on the data in each document. We have nunjucks templates, tags and filters that\ncan render links and text as markdown and will highlight code.\n\n### Services\n\n* `nunjucks-template-engine` - provide a `templateEngine` that uses the Nunjucks template library\nto render the documents into text, such as HTML or JS, based on templates.\n\n## `jsdoc` Package\n\n### File Readers:\n\n* `jsdoc` - can read documents from jsdoc style comments in source code files.\n\n### Processors\n\n* `codeNameProcessor` - infer the name of the document from the code following the document in the source\nfile.\n* `extractTagsProcessor` - use a `tagExtractor` to extract information from the parsed tags.\n* `inlineTagsProcessor` - Search the docs for inline tags that need to have content injected\n* `parseTagsProcessor` - use a `tagParser` to parses the jsdoc tags in the document content.\n\n### Tag Definitions\n\nThe `jsdoc` package contains definitions for a number of standard jsdoc tags including: `name`,\n`memberof`, `param`, `property`, `returns`, `module`, `description`, `usage`,\n`animations`, `constructor`, `class`, `classdesc`, `global`, `namespace`, `method`, `type` and\n`kind`.\n\n### Services (Tag Transformations)\n\nThis package provides a number of **Transform** services that are used in **Tag Definitions** to transform\nthe value of the tag from the string in the tag description to something more meaningful in the doc.\n\n* `extractNameTransform` - extract a name from a tag\n* `extractTypeTransform` - extract a type from a tag\n* `trimWhitespaceTransform` - trim whitespace from before and after the tag value\n* `unknownTagTransform` - add an error to the tag if it is unknown\n* `wholeTagTransform` - Use the whole tag as the value rather than using a tag property\n\n### Templates\n\n**This package does not provide any templates nor a `templateEngine` to render templates (use the\n`nunjucks` package to add this).**\n\n### Tag Definitions\n\nThis package provides a minimal implementation of tags from the JSDoc project. They extract the name\nand type from the tag description accordingly but do not fully implement all the JSDoc tag functionality.\n\n## `ngdoc` Package\n\nThe `ngdoc` Package depends upon the `jsdoc` and `nunjucks` packages. It provides additional support for\nnon-API documents written in files with `.ngdoc` extension; it also computes additional properties specific\nto Angular related code.\n\n## File Readers\n\n* `ngdoc` - can pull a single document from an ngdoc content file.\n\n### Processors\n\n* `filterNgdocsProcessor` -\nFor AngularJS we are only interested in documents that contain the @ngdoc tag. This processor\nremoves docs that do not contain this tag.\n\n* `generateComponentGroupsProcessor` -\nGenerate documents for each group of components (by type) within a module\n\n* `memberDocsProcessor` - This processor connects docs that are members (properties, methods and events) to\ntheir container docs, removing them from the main docs collection.\n\n* `moduleDocsProcessor` - This processor computes properties for module docs such as `packageName` and\n`packageFileName`; it adds modules to the `moduleMap` service and connects all the docs that are in a module\nto the module doc in the `components` property\n\n* `providerDocsProcessor` - This processor relates documents about angular services to their corresponding\nprovider document.\n\n\n### Tag Definitions\n\nThis package modifies and adds new tag definitions on top of those provided by the `jsdoc` package:\n`area`, `element`, `eventType`, `example`, `fullName`, `id`, `module`, `name`, `ngdoc`, packageName`,\n`parent`, `priority`, `restrict`, `scope` and `title`.\n\n\n### Inline Tag Definitions\n\n* `link` - Process inline link tags (of the form {@link some/uri Some Title}), replacing them with\nHTML anchors\n\n\n### Services\n\n* `getAliases()` - Get a list of all the aliases that can be made from the provided doc\n* `getDocFromAliases()` - Find a document from the `aliasMap` that matches the given alias\n* `getLinkInfo()` - Get link information to a document that matches the given url\n* `getTypeClass()` - Get a CSS class string for the given type string\n* `moduleMap` - A collection of modules keyed on the module id\n\n\n### Templates\n\nThis package provides a set of templates for generating an HTML file for each document: api,\ndirective, error, filter function, input, module, object, overview, provider, service, type and a\nnumber to support rendering of the runnable examples.\n\nYou should be aware that because of the overlap in syntax between Nunjucks bindings and AngularJS\nbindings, the ngdoc package changes the default Nunjucks binding tags:\n\n```js\ntemplateEngine.config.tags = {\n variableStart: '{$',\n variableEnd: '$}'\n};\n```\n\n### Rendering Filters\n\n* `code` - Render a span of text as code\n* `link` - Render a HTML anchor link\n* `typeClass` - Render a CSS class for a given type\n\n### Rendering Tags\n\n* `code` - Render a block of code\n\n\n## `examples` Package\n\nThis package is a mix-in that provides functionality for working with examples in the docs.\n\nInside your docs you can markup inline-examples such as:\n\n```\nSome text before the example\n\n<example name=\"example-name\">\n <file name=\"index.html\">\n <div>The main HTML for the example</div>\n </file>\n <file name=\"app.js\">\n // Some JavaScript code to be included in the example\n </file>\n</example>\n\nSome text after the example\n```\n\n\n### Processors\n\n* `generateExamplesProcessor` - Add new docs to the docs collection for each example in the `examples` service\nthat will be rendered as files that can be run in the browser, for example as live in-place demos of the\nexamples or for e2e testing. This processor must be configured with a collection of deployments that tell it\nwhat versions of each example to generate. See the section of **Deployment Configuration** below.\n* `parseExamplesProcessor` - Parse the `<example>` tags from the content and add them to the `examples` service\n* `generateProtractorTestsProcessor` - Generate a protractor test files from the e2e tests in the examples. This processor\nmust be configured with a collection of deployments that tell versions of the protractor tests to generate. See the\nsection of **Deployment Configuration** below.\n\n#### Deployment Configuration\n\nThe `generateExamplesProcessor` and `generateProtractorTestsProcessor` processors have a *required* property called `deployments`.\nThis property should be an array of deployment information objects telling the processor what files to generate.\n\nFor instance you might have a \"debug\" deployment that loads angular.js into the example, and also a \"default\" deployment that\nloads angular.min.js into the example. Equally you might have deployments that use JQuery and some that only use Angular's\njqLite.\n\nYou can configure this in your package like so:\n\n```js\n.config(function(generateExamplesProcessor, generateProtractorTestsProcessor) {\n var deployments = [\n { name: 'debug', ... },\n { name: 'default', ... }\n ];\n\n generateExamplesProcessor.deployments = deployments;\n generateProtractorTestsProcessor.deployments = deployments;\n});\n```\n\nA deployment can must have a `name` property and can also include an `examples` property that contains\ninformation about paths and extra files to inject into runtime examples.\nFurther a protractor test is generated for each deployment and it uses the deployment name to find the\npath to the associated example for that deployment.\n\n```js\n{\n name: 'default',\n examples: {\n commonFiles: {\n scripts: [ '../../../angular.js' ]\n },\n dependencyPath: '../../../'\n }\n}\n```\n\nHere you can see we have a `default` deployment that injects the `angular.js` file into all examples,\nplus any dependencies referenced in the example itself are made relative to the given `dependencyPath`.\n\n### Inline Tag Definitions\n\n* `runnableExample` - Inject the specified runnable example into the doc\n\n\n### Services\n\n* `exampleMap` - a hash map holding each example by id, which is a unique id generated from the name\nof the example\n\n",
"readmeFilename": "README.md",
"homepage": "https://github.com/angular/dgeni-packages",
"_id": "dgeni-packages@0.10.3",
"_shasum": "24eddcd2756fbc954db82a6c77ab89041cb39dab",
"_resolved": "git+https://github.com/msvbg/dgeni-packages.git#3a7c4c5777175f3567d5d6a1c5d3d13b5ade8732",
"_from": "git+https://github.com/msvbg/dgeni-packages.git"
}