The node.js documentation generation utility by angular.js and other projects.
Try out the Dgeni example project at https://github.com/petebacondarwin/dgeni-example
You'll need node.js and a bunch of npm modules installed to use Dgeni. Get node.js from here: http://nodejs.org/.
In the project you want to document you install Dgeni by running:
npm install dgeni --save
This will install Dgeni and any modules that Dgeni depends upon.
Dgeni on its own doesn't do much. You much configure it with Packages that contain Services and Processors. It is the Processors that actually convert your source files to documentation files.
To the run the processors we create a new instance of Dgeni, providing to it an array of Packages
to load. Then simply call the generate() method on this instance. The generate() method runs the
processors asynchronously and returns a Promise to the generated documents.
var Dgeni = require('dgeni');
var packages = [require('./myPackage')];
var dgeni = new Dgeni(packages);
dgeni.generate().then(function(docs) {
console.log(docs.length, 'docs generated');
});
Services, Processors, configuration values and templates are be bundled into a Package. Packages
can depend upon other Packages. In this way you can build up your custom configuration on
top of an existing configuration.
Dgeni provides a Package type that you instantiate. This instance has methods to register Services and
Processors, and to configure the properties of Processors:
var Package = require('dgeni').Package;
var myPackage = new Package('myPackage', ['packageDepencency1', 'packageDependency2']);
myPackage.processor(requre('./processors/processor1'));
myPackage.processor(require('./processors/processor2'));
myPackage.factory(require('./services/service1'));
myPackage.factory(require('./services/service2'));
myPackage.config(function(processor1, service2) {
service2.someProperty = 'some value';
processor1.specialService = service2;
});
Dgeni makes significant use of Dependency Injection (DI) to instantiate objects. Objects that
will be instantiated by the DI system must be provided by a factory function, which is registered
in a Package, either as a Processor, by myPackage.processor(factoryFn), or as a Service,
by myPackage.factory(factoryFn).
The parameters to a factory function are dependencies on other services that the DI system must find or instantiate and provide to the factory function.
module.exports = function car(function(engine, wheels) {
return {
drive: function() {
engine.start();
wheels.turn();
}
};
})
Here we have defined a car service, which depends upon two other services, engine and wheels
defined elsewhere. Note that this car service doesn't care how and where these dependencies are
defined. It relies on the DI system to provide them when needed.
The car service returned by the factory function is an object containing one method, drive(),
which in turn calls methods on engine and wheels.
Processors are Services that contain a $process(docs) method. The processors are run
one after another in a pipeline. Each Processor takes the collection documents from the previous
Processor and manipulates it, maybe inserting new documents or adding meta data to documents that are
there already.
Processors can expose properties that tell Dgeni where in the pipeline they should be run and how to validate the configuration of the Processor.
$enabled - if set to false then this Processor will not be included in the pipeline$runAfter - an array of strings, where each string is the name of a Processor that must appear
earlier in the pipeline than this Processor$runBefore - an array of strings, where each string is the name of a Processor that must appear
later in the pipeline than this one$validate - a http://validatejs.org/ constraint object that Dgeni uses
to validate the properties of this Processor.You define Processors just like you would a Service:
myDocProcessor.js:
module.exports = function myDocProcessor(dependency1, dependency2) {
return {
$process(docs) { ... do stuff with the docs ... }
$runAfter: ['otherProcessor1'],
$runBefore: ['otherProcessor2', 'otherProcessor3'],
$validate: {
myProperty: { presence: true }
},
myProperty: 'some config value'
};
You then register the Processor with a Package: myPackage.js:
var Package = require('dgeni').Package;
module.exports = new Package('myPackage')
.processor(require('./myDocProcessor'));
The $process(docs) method can be synchronous or asynchronous:
undefined or a new array of documents.
If it returns a new array of docs then this array will replace the previous docs array.undefined
or a new collection of documents. By returning a Promise, the processor tells Dgeni
that it is asynchronous and Dgeni will wait for the promise to resolve before calling the
next processor.Here is an example of an asynchronous Processor
var qfs = require('q-io/fs');
module.exports = function readFileProcessor() {
return {
filePath: 'some/file.js',
$process(docs) {
return qfs.readFile(this.filePath).then(function(response) {
docs.push(response.data);
});
}
};
The dgeni-packages repository contains a many Processors
base - contains the basic file reading and writing Processors as well as an abstract
rendering Processor.jsdoc - depends upon base and adds Processors and Services to support parsing and
extracting jsdoc style tags from comments in code.nunjucks - provides a nunjucks based rendering
engine.ngdoc - depends upon jsdoc and nunjucks and adds additional processing for the
AngularJS extensions to jsdoc.examples - depends upon jsdoc and provides Processors for extracting examples from jsdoc
comments and converting them to files that can be run.There are a number of processors that don't do anything but act as markers for stages of the
processing. You can use these markers in $runBefore and $runAfter properties to ensure
that your Processor is run at the right time. Here is a list of these marker processors in order:
You can configure the Services and Processors defined in a Package or its dependencies by registering Configuration Blocks with the Package. These are functions that can be injected with Services and Processors by the DI system, giving you the opportunity to set properties on them.
You register a Configuration Block by calling config(configFn) on a Package.
myPackage.config(function(readFilesProcessor) {
readFilesProcessor.sourceFiles = ['src/**/*.js'];
});
v0.4.0-beta.1 (25th July 2014)
This is a major re-architecting of how Dgeni uses Dependency Injection and configuration.
This version of Dgeni is compatible with dgeni-packages@^0.10.0
$. E.g. $process(),
$runBefore, $runAfter.processor.$validate property.processor.$enabled = false.dgeni, log, getInjectables.log service in your Processors and Services instead of requiring winston.The most significant commits are listed below:
$enabled: false d390fcd3FAQs
Flexible JavaScript documentation generator used by both AngularJS and Angular
The npm package dgeni receives a total of 5,545 weekly downloads. As such, dgeni popularity was classified as popular.
We found that dgeni demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.