README
Dgeni Packages
This repository contains a collection of Dgeni Packages that can be used by the Dgeni documentation generator to create documentation from source code.
Out of the box there are the following packages:
- base - The minimal set of processors to get started with Dgeni
- git - Provides some git and version information
- jsdoc - Tag parsing and extracting
- nunjucks - The nunjucks template rendering engine. No longer in jsdoc - you must add this
explicitly to your config or you will get
Error: No provider for "templateEngine"! (Resolving: templateEngine)
- ngdoc - The angular.js specific tag-defs, processors and templates. This loads the jsdoc and nunjucks packages for you.
- examples - Processors to support the runnable examples feature in the angular.js docs site.
- dgeni - Support for documenting Dgeni packages (incomplete)
- typescript - Tag parsing and extracting for TypeScript modules.
Package base
Processors
computeIdsProcessor
- Computes theid
andaliases
for documents using templates or helper functions, on a per docType basis.computePathsProcessor
- Computes thepath
andoutputPath
for documents using templates or helper functions, on a per docType basis.debugDumpProcessor
- dump the current state of the docs array to a file (disabled by default)readFilesProcessor
- used to load up documents from files. This processor can be configured to use a set of file readers. There are file readers in thejsdoc
andngdoc
packages.renderDocsProcessor
- render the documents into a property (doc.renderedContent
) using atemplateEngine
, which must be provided separately - seenunjucks
package.unescapeCommentsProcessor
- unescape comment markers that would break the jsdoc comment style, e.g.*/
writeFilesProcessor
- write the docs that have anoutputPath
to disk
Services
aliasMap
- A map of ids/aliases to docs. This is used for matching references to documents in links and relations such as modules and object members.createDocMessage
- a helper for creating nice messages about documents (useful in logging and errors)encodeDocBlock
- convert a block of code into HTMLtemplateFinder
- search folders using patterns to find a template that matches a given document.trimIndentation
- "intelligently" trim whitespace indentation from the start of each line of a block of text.writeFile
- Write some contents to a file, ensuring the path to the file exists.
Template Finding
The template used to render a doc is computed by the templateFinder
, which uses the first match
from a set of patterns in a set of folders, provided in the configuration. This allows a lot of control to provide
generic templates for most situations and specific templates for exceptional cases.
Here is an example of some standard template patterns:
templateFinder.templatePatterns = [
'${ doc.template }',
'${ doc.area }/${ doc.id }.${ doc.docType }.template.html',
'${ doc.area }/${ doc.id }.template.html',
'${ doc.area }/${ doc.docType }.template.html',
'${ doc.id }.${ doc.docType }.template.html',
'${ doc.id }.template.html',
'${ doc.docType }.template.html'
]
Package git
This package provides some git and version information to the renderDocsPocessor
that is available
in the templates. This code as it is was made for the angular.js document generation, including some
custom logic for special versions. However, any of the services can be overridden with custom
behavior.
The git information is made available to templates via the extraData.git
property. See the section
below to see an example usage.
Services
decorateVersion
- all semvers are passed through this function so that additional data can before added to them.getPreviousVersions
- pulls versions from git tags of the repository.gitData
- the additional information that is added to the extraData ofrenderDocsPocessor
.gitRepoInfo
- the owner and repo of the local git repository.packageInfo
- the contents of the package.json.versionInfo
- aggregated version and git information.
extraData.git
Using An example as used in git/templates/api/api.template.html
<a href='https://github.com/{$ git.info.owner $}/{$ git.info.repo $}/tree/{$ git.version.isSnapshot and 'master' or git.version.raw $}/{$ doc.fileInfo.projectRelativePath $}#L{$ doc.startingLine $}' class='view-source pull-right btn btn-primary'>
<i class="glyphicon glyphicon-zoom-in"> </i>View Source
</a>
Package nunjucks
This package provides a nunjucks driven implementation of the templateEngine
required by the
base
package renderDocsPocessor
. The "nunjucks" JavaScript template tool-kit to generates HTML
based on the data in each document. We have nunjucks templates, tags and filters that
can render links and text as markdown and will highlight code.
Services
nunjucks-template-engine
- provide atemplateEngine
that uses the Nunjucks template library to render the documents into text, such as HTML or JS, based on templates.
Package jsdoc
File Readers
jsdoc
- can read documents from jsdoc style comments in source code files.
Processors
codeNameProcessor
- infer the name of the document from the code following the document in the source file.extractTagsProcessor
- use atagExtractor
to extract information from the parsed tags.inlineTagsProcessor
- Search the docs for inline tags that need to have content injectedparseTagsProcessor
- use atagParser
to parses the jsdoc tags in the document content.
Tag Definitions
The jsdoc
package contains definitions for a number of standard jsdoc tags including: name
,
memberof
, param
, property
, returns
, module
, description
, usage
,
animations
, constructor
, class
, classdesc
, global
, namespace
, method
, type
,
kind
, access
, public
, private
and protected
.
Services (Tag Transformations)
This package provides a number of Transform services that are used in Tag Definitions to transform the value of the tag from the string in the tag description to something more meaningful in the doc.
extractAccessTransform
- extract an access level (e.g. public, protected, private) from tags You can configure this transform to register access tags and set the property where access info is written.extractAccessTransform.allowedTags.set('tagName', [propertValue])
- register a tag that can act as as an alias to set an access level. The propertyValue is optional and if not undefined will return this value from the transform that will be written to the property. (defaults topublic:undefined
,private:undefined
,protected:undefined
)extractAccessTransformImpl.allowedDocTypes.set('docType')
- register a docType that can contain access type tags (defaults to "property" and "method")extractAccessTransformImpl.accessProperty
- specify the property to which to write the access value (defaults to "access")extractAccessTransformImpl.accessTagName
- specify the name of the tag that can hold access values (defaults to "access")
extractNameTransform
- extract a name from a tagextractTypeTransform
- extract a type from a tagtrimWhitespaceTransform
- trim whitespace from before and after the tag valueunknownTagTransform
- add an error to the tag if it is unknownwholeTagTransform
- Use the whole tag as the value rather than using a tag propertycodeNameService
- helper service forcodeNameProcessor
, registers code name matchers and performs actual matches against AST tree
Templates
This package does not provide any templates nor a templateEngine
to render templates (use the
nunjucks
package to add this).
Tag Definitions
This package provides a minimal implementation of tags from the JSDoc project. They extract the name and type from the tag description accordingly but do not fully implement all the JSDoc tag functionality.
Code Name Matchers
Matcher performs a search for a suitable code name at the given jsdoc code point (AST node).
codeNameService
matches AST node name against matcher name and if suitable matcher is found, executes it.
Matcher name consists of <AstNodeName>
and NodeMatcher
substrings, i.e. FunctionExpressionNodeMatcher
then latter is stripped and matcher is used by the former part, i.e. FunctionExpression
.
Matcher should accept single argument - node and return either string with name or literal null
.
Matchers:
ArrayExpression
ArrowFunctionExpression
AssignmentExpression
CallExpression
ClassDeclaration
ExportDefaultDeclaration
ExpressionStatement
FunctionDeclaration
FunctionExpression
Identifier
Literal
MemberExpression
MethodDefinition
NewExpression
ObjectExpression
Program
Property
ReturnStatement
ThrowStatement
VariableDeclaration
VariableDeclarator
Package ngdoc
The ngdoc
Package depends upon the jsdoc
and nunjucks
packages. It provides additional support for
non-API documents written in files with .ngdoc
extension; it also computes additional properties specific
to Angular related code.
File Readers
ngdoc
- can pull a single document from an ngdoc content file.
Processors
filterNgdocsProcessor
- For AngularJS we are only interested in documents that contain the @ngdoc tag. This processor removes docs that do not contain this tag.generateComponentGroupsProcessor
- Generate documents for each group of components (by type) within a modulememberDocsProcessor
- This processor connects docs that are members (properties, methods and events) to their container docs, removing them from the main docs collection.moduleDocsProcessor
- This processor computes properties for module docs such aspackageName
andpackageFileName
; it adds modules to themoduleMap
service and connects all the docs that are in a module to the module doc in thecomponents
propertyproviderDocsProcessor
- This processor relates documents about angular services to their corresponding provider document.
Tag Definitions
This package modifies and adds new tag definitions on top of those provided by the jsdoc
package:
area
, element
, eventType
, example
, fullName
, id
, module
, name
, ngdoc
, packageName
,
parent
, priority
, restrict
, scope
and title
.
Inline Tag Definitions
link
- Process inline link tags (of the form {@link some/uri Some Title}), replacing them with HTML anchors
Services
getAliases()
- Get a list of all the aliases that can be made from the provided docgetDocFromAliases()
- Find a document from thealiasMap
that matches the given aliasgetLinkInfo()
- Get link information to a document that matches the given urlgetTypeClass()
- Get a CSS class string for the given type stringmoduleMap
- A collection of modules keyed on the module id
Templates
This package provides a set of templates for generating an HTML file for each document: api, directive, error, filter function, input, module, object, overview, provider, service, type and a number to support rendering of the runnable examples.
You should be aware that because of the overlap in syntax between Nunjucks bindings and AngularJS bindings, the ngdoc package changes the default Nunjucks binding tags:
templateEngine.config.tags = {
variableStart: '{