{"id":13546560,"url":"https://github.com/angular/dgeni","last_synced_at":"2025-05-15T11:07:44.468Z","repository":{"id":13198204,"uuid":"15881968","full_name":"angular/dgeni","owner":"angular","description":"Flexible JavaScript documentation generator used by AngularJS, Protractor and other JS projects","archived":false,"fork":false,"pushed_at":"2022-06-30T12:58:01.000Z","size":4977,"stargazers_count":772,"open_issues_count":21,"forks_count":66,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-05-15T00:21:31.917Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/angular.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-13T21:12:13.000Z","updated_at":"2025-03-25T11:50:50.000Z","dependencies_parsed_at":"2022-09-17T05:01:17.888Z","dependency_job_id":null,"html_url":"https://github.com/angular/dgeni","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angular%2Fdgeni","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angular%2Fdgeni/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angular%2Fdgeni/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angular%2Fdgeni/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angular","download_url":"https://codeload.github.com/angular/dgeni/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328384,"owners_count":22052632,"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":[],"created_at":"2024-08-01T12:00:40.182Z","updated_at":"2025-05-15T11:07:44.444Z","avatar_url":"https://github.com/angular.png","language":"TypeScript","funding_links":[],"categories":["Docs"],"sub_categories":[],"readme":"# Dgeni - Documentation Generator [![Build Status](https://travis-ci.org/angular/dgeni.svg?branch=master)](https://travis-ci.org/angular/dgeni)\n\n![](assets/dgeni-logo-600x400.png)\n\nThe node.js documentation generation utility by angular.js and other projects.\n\nDgeni is pronounced like the girl name Jenny ([/ˈdʒɛni/](https://en.wikipedia.org/wiki/Help:IPA_for_English)),\ni.e the `d` is silent and the `g` is soft.\n\n## Getting started\n\nTry out the Dgeni [example project](https://github.com/petebacondarwin/dgeni-example). Or maybe you're looking for an example [using AngularJS](https://github.com/petebacondarwin/dgeni-angular).\n\nWatch Pete's ng-europe talk on Dgeni :\n\n[![ScreenShot](http://img.youtube.com/vi/PQNROxXajyQ/0.jpg)](http://youtu.be/PQNROxXajyQ)\n\n\n## Documenting AngularJS Apps\n\nThere are two projects out there that build upon dgeni to help create documentation for AngularJS apps:\n\n* dgeni-alive: https://github.com/wingedfox/dgeni-alive\n* sia: https://github.com/boundstate/sia\n\nDo check them out and thanks to [Ilya](https://github.com/wingedfox) and [Bound State Software](https://github.com/boundstate)\nfor putting these projects together.\n\n## Installation\n\nYou'll need node.js and a bunch of npm modules installed to use Dgeni.  Get node.js from here:\nhttp://nodejs.org/.\n\nIn the project you want to document you install Dgeni by running:\n\n```\nnpm install dgeni --save-dev\n```\n\nThis will install Dgeni and any modules that Dgeni depends upon.\n\n\n## Running Dgeni\n\nDgeni on its own doesn't do much.  You must configure it with **Packages** that contain **Services**\nand **Processors**. It is the **Processors** that actually convert your source files to\ndocumentation files.\n\nTo run the processors we create a new instance of `Dgeni`, providing to it an array of **Packages**\nto load.  Then simply call the `generate()` method on this instance.  The `generate()` method runs the\nprocessors asynchronously and returns a **Promise** that gets fulfilled with the generated documents.\n\n```js\nvar Dgeni = require('dgeni');\n\nvar packages = [require('./myPackage')];\n\nvar dgeni = new Dgeni(packages);\n\ndgeni.generate().then(function(docs) {\n  console.log(docs.length, 'docs generated');\n});\n```\n\n### Running from the Command Line\n\nDgeni is normally used from a build tool such as Gulp or Grunt but it does also come with a\ncommand line tool.\n\nIf you install Dgeni globally then you can run it from anywhere:\n\n```bash\nnpm install -g dgeni\ndgeni some/package.js\n```\n\nIf Dgeni is only installed locally then you either have to specify the path explicitly:\n\n```bash\nnpm install dgeni\nnode_modules/.bin/dgeni some/package.js\n```\n\nor you can run the tool in an npm script:\n\n```js\n{\n  ...\n  scripts: {\n    docs: 'dgeni some/package.js'\n  }\n  ...\n}\n```\n\n\nThe usage is:\n\n\n```bash\ndgeni path/to/mainPackage [path/to/other/packages ...] [--log level]\n```\n\nYou must provide the path to one or more Dgeni Packages to load. You can, optionally, set\nthe logging level.\n\n\n## Packages\n\n**Services**, **Processors**, configuration values and templates are be bundled into a `Package`.  Packages\ncan depend upon other Packages.  In this way you can build up your custom configuration on\ntop of an existing configuration.\n\n### Defining a Package\n\nDgeni provides a `Package` constructor to create new Packages.  A Package instance has methods to register **Services** and\n**Processors**, and to configure the properties of **Processors**:\n\n```js\nvar Package = require('dgeni').Package;\nvar myPackage = new Package('myPackage', ['packageDepencency1', 'packageDependency2']);\n\nmyPackage.processor(require('./processors/processor1'));\nmyPackage.processor(require('./processors/processor2'));\n\nmyPackage.factory(require('./services/service1'));\nmyPackage.factory(require('./services/service2'));\n\nmyPackage.config(function(processor1, service2) {\n  service2.someProperty = 'some value';\n  processor1.specialService = service2;\n});\n```\n\n\n## Services\n\nDgeni makes significant use of **Dependency Injection (DI)** to instantiate objects.  Objects that\nwill be instantiated by the DI system must be provided by a **factory function**, which is registered\nin a **Package**, either as a **Processor**, by `myPackage.processor(factoryFn)`, or as a **Service**,\nby `myPackage.factory(factoryFn)`.\n\n### Defining a Service\n\nThe parameters to a factory function are dependencies on other services that the DI system must find\nor instantiate and provide to the factory function.\n\n**car.js**:\n```js\nmodule.exports = function car(engine, wheels) {\n  return {\n    drive: function() {\n      engine.start();\n      wheels.turn();\n    }\n  };\n};\n```\n\nHere we have defined a `car` service, which depends upon two other services, `engine` and `wheels`\ndefined elsewhere.  Note that this `car` service doesn't care how and where these dependencies are\ndefined. It relies on the DI system to provide them when needed.\n\nThe `car` service returned by the factory function is an object containing one method, `drive()`,\nwhich in turn calls methods on `engine` and `wheels`.\n\n\n### Registering a Service\n\nYou then register the Service with a Package:\n\n**myPackage.js**:\n```jsv\nvar Package = require('dgeni').Package;\n\nmodule.exports = new Package('myPackage')\n  .factory(require('./car'));\n```\n\nThis car Service is then available to any other Service, Processor or configuration block:\n\n```js\nvar Package = require('dgeni').Package;\n\nmodule.exports = new Package('greenTaxiPackage', ['myPackage'])\n\n  .factory(function taxi(car) {\n    return {\n      orderTaxi: function(place) { car.driveTo(place); }\n    };\n  })\n\n  .config(function(car) {\n    car.fuel = 'hybrid';\n  });\n```\n\n\n## Processors\n\n**Processors** are **Services** that contain a `$process(docs)` method.  The processors are run\none after another in a pipeline. Each Processor takes the collection documents from the previous\nProcessor and manipulates it, maybe inserting new documents or adding meta data to documents that are\nthere already.\n\nProcessors can expose properties that tell Dgeni where in the pipeline they should be run and\nhow to validate the configuration of the Processor.\n\n* `$enabled` - if set to `false` then this Processor will not be included in the pipeline\n* `$runAfter` - an array of strings, where each string is the name of a Processor that must appear\n**earlier** in the pipeline than this Processor\n* `$runBefore` - an array of strings, where each string is the name of a Processor that must appear\n**later** in the pipeline than this one\n* `$validate` - a [http://validatejs.org/](http://validatejs.org/) constraint object that Dgeni uses\nto validate the properties of this Processor.\n\n\n**Note that the validation feature has been moved to its own Dgeni Package `processorValidation`.\nCurrently dgeni automatically adds this new package to a new instance of dgeni so that is still available\nfor backward compatibility. In a future release this package will be moved to `dgeni-packages`.**\n\n### Defining a Processor\n\nYou define Processors just like you would a Service:\n\n**myDocProcessor.js**:\n```js\nmodule.exports = function myDocProcessor(dependency1, dependency2) {\n  return {\n    $process: function (docs) {\n        //... do stuff with the docs ...\n    },\n    $runAfter: ['otherProcessor1'],\n    $runBefore: ['otherProcessor2', 'otherProcessor3'],\n    $validate: {\n      myProperty: { presence: true }\n    },\n    myProperty: 'some config value'\n  };\n};\n```\n\n\n### Registering a Processor\n\nYou then register the Processor with a Package:\n**myPackage.js**:\n```jsv\nvar Package = require('dgeni').Package;\n\nmodule.exports = new Package('myPackage')\n  .processor(require('./myDocProcessor'));\n```\n\n### Asynchronous Processing\n\nThe `$process(docs)` method can be synchronous or asynchronous:\n\n* If synchronous then it should return `undefined` or a new array of documents.\nIf it returns a new array of docs then this array will replace the previous `docs` array.\n* If asynchronous then it must return a **Promise**, which should resolve to an array of\ndocuments that will replace the previous array. By returning a **Promise**, the processor\ntells Dgeni that it is asynchronous and Dgeni will wait for the promise to resolve before\ncalling the next processor.\n\n\nHere is an example of an asynchronous **Processor**\n```js\nvar qfs = require('q-io/fs');\nmodule.exports = function readFileProcessor() {\n  return {\n    filePath: 'some/file.js',\n    $process(docs) {\n      return qfs.readFile(this.filePath).then(function(response) {\n        docs.push(response.data);\n        return docs;\n      });\n    }\n  };\n```\n\n### Standard Dgeni Packages\n\nThe [dgeni-packages repository](https://github.com/angular/dgeni-packages) contains many Processors -\nfrom basic essentials to complex, angular.js specific.  These processors are grouped into Packages:\n\n* `base` -  contains the basic file reading and writing Processors as well as an abstract\nrendering Processor.\n\n* `jsdoc` - depends upon `base` and adds Processors and Services to support parsing and\nextracting jsdoc style tags from comments in code.\n\n* `typescript` - depends upon `base` and adds Processors and Services to support parsing and\nextracting jsdoc style tags from comments in TypeScript (*.ts) code.\n\n* `nunjucks` - provides a [nunjucks](http://mozilla.github.io/nunjucks/) based rendering\nengine.\n\n* `ngdoc` - depends upon `jsdoc` and `nunjucks` and adds additional processing for the\nAngularJS extensions to jsdoc.\n\n* `examples` - depends upon `jsdoc` and provides Processors for extracting examples from jsdoc\ncomments and converting them to files that can be run.\n\n* `dgeni` - support for documenting dgeni Packages.\n\n\n### Pseudo Marker Processors\n\nYou can define processors that don't do anything but act as markers for stages of the\nprocessing.  You can use these markers in `$runBefore` and `$runAfter` properties to ensure\nthat your Processor is run at the right time.\n\nThe **Packages** in dgeni-packages define some of these marker processors. Here is a list\nof these in the order that Dgeni will add them to the processing pipeline:\n\n\n* reading-files *(defined in base)*\n* files-read *(defined in base)*\n* parsing-tags *(defined in jsdoc)*\n* tags-parsed *(defined in jsdoc)*\n* extracting-tags *(defined in jsdoc)*\n* tags-extracted *(defined in jsdoc)*\n* processing-docs *(defined in base)*\n* docs-processed *(defined in base)*\n* adding-extra-docs *(defined in base)*\n* extra-docs-added *(defined in base)*\n* computing-ids *(defined in base)*\n* ids-computed *(defined in base)*\n* computing-paths *(defined in base)*\n* paths-computed *(defined in base)*\n* rendering-docs *(defined in base)*\n* docs-rendered *(defined in base)*\n* writing-files *(defined in base)*\n* files-written *(defined in base)*\n\n\n## Configuration Blocks\n\nYou can configure the **Services** and **Processors** defined in a **Package** or its dependencies\nby registering **Configuration Blocks** with the **Package**.  These are functions that can be\ninjected with **Services** and **Processors** by the DI system, giving you the opportunity to\nset properties on them.\n\n\n### Registering a Configuration Block\n\nYou register a **Configuration Block** by calling `config(configFn)` on a Package.\n\n```js\nmyPackage.config(function(readFilesProcessor) {\n  readFilesProcessor.sourceFiles = ['src/**/*.js'];\n});\n```\n\n## Dgeni Events\n\nIn Dgeni you can trigger and handle **events** to allow packages to take part in the processing\nlifecycle of the documentation generation.\n\n\n### Triggering Events\n\nYou trigger an event simply by calling `triggerEvent(eventName, ...)` on a `Dgeni` instance.\n\nThe `eventName` is a string that identifies the event to be triggered, which is used to wire up\nevent handlers. Additional arguments are passed through to the handlers.\n\nEach handler that is registered for the event is called in series. The return value\nfrom the call is a promise to the event being handled. This allows event handlers to be async.\nIf any handler returns a rejected promise the event triggering is cancelled and the rejected\npromise is returned.\n\nFor example:\n\n```js\nvar eventPromise = dgeni.triggerEvent('someEventName', someArg, otherArg);\n```\n\n### Handling Events\n\nYou register an event handler in a `Package`, by calling `handleEvent(eventName, handlerFactory)` on\nthe package instance. The handlerFactory will be used by the DI system to get the handler, which allows\nyou to inject services to be available to the handler.\n\nThe handler factory should return the handler function. This function will receive all the arguments passed\nto the `triggerHandler` method. As a minimum this will include the `eventName`.\n\nFor example:\n\n```js\nmyPackage.eventHandler('generationStart', function validateProcessors(log, dgeni) {\n  return function validateProcessorsImpl(eventName) {\n    ...\n  };\n});\n\n```\n\n### Built-in Events\n\nDgeni itself triggers the following events during documentation generation:\n\n* `generationStart`: triggered after the injector has been configured and before the processors begin\n  their work.\n* `generationEnd`: triggered after the processors have all completed their work successfully.\n* `processorStart`: triggered just before the call to `$process`, for each processor.\n* `processorEnd`: triggered just after `$process` has completed successfully, for each processor.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangular%2Fdgeni","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangular%2Fdgeni","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangular%2Fdgeni/lists"}