gulp-ngdocs
This is a fork of nikhilmodak's ngdocs (https://github.com/nikhilmodak/gulp-ngdocs). I did not write any of this code, just added one if statement that makes sure this plugin also checks TypeScript files.
Gulp plugin for building AngularJS like documentation. This is inspired from grunt-ngdocs.
Setup
npm install gulp-ngdocs --save-dev
Usage
Create a ngdocs
gulp task
gulp;
Create a ngdocs
gulp task with options
gulp;
To use a different angularjs version pass angular
and angular-animate
files in scripts.
gulp;
If you would like to divide your documentation into different sections, use gulpDocs.sections
instead of gulp.src
.
gulp;
Doc comment example
A doc comment looks like this:
/** * @ngdoc directive * @name rfx.directive:rAutogrow * @element textarea * @function * * @description * Resize textarea automatically to the size of its text content. * * **Note:** ie<9 needs pollyfill for window.getComputedStyle * * @example <example module="rfx"> <file name="index.html"> <textarea ng-model="text"rx-autogrow class="input-block-level"></textarea> <pre>{{text}}</pre> </file> </example> */angular;
Check out the Writing AngularJS documentation wiki article to see what's possible, or take a look at the AngularJS source code for more examples.
Options
scripts
Set addional custom js files are loaded to the app. This allows the live examples to use custom directives, services, etc. The documentation app works with angular.js 1.2+ and 1.3+. If you include your own angular.js include angular-animate.js too.
Possible values:
- ['path/to/file.js'] file will be copied into the docs, into a
js
folder - ['http://example.com/file.js', 'https://example.com/file.js', '//example.com/file.js'] reference remote files (eg from a CDN)
- ['../app.js'] reference file relative to the dest folder
styles
[default] []
Copy additional css files to the documentation app
analytics
Optional include Google Analytics in the documentation app.
discussions
Optional include discussions in the documentation app.
editExample
[default] true
Show Edit Button for examples.
title
[default] "API Documentation"
Title to put on the navbar and the page's title
attribute.
startPage
[default] '/api'
Set first page to open.
html5Mode
[default] true
Whether or not to enable html5Mode
in the docs application. If true, then links will be absolute. If false, they will be prefixed by #/
.
image
A URL or relative path to an image file to use in the top navbar.
titleLink
[default] no anchor tag is used Wraps the title text in an anchor tag with the provided URL.
imageLink
[default] no anchor tag is used Wraps the navbar image in an anchor tag with the provided URL.
bestMatch
[default] false
The best matching page for a search query is highlighted and get selected on return.
If this option is set to true the best match is shown below the search field in an dropdown menu. Use this for long lists where the highlight is often not visible.
navTemplate
[default] null
Path to a template of a nav HTML template to include. The css for it
should be that of listitems inside a bootstrap navbar:
{{links to all the docs pages}} {{YOUR_NAV_TEMPLATE_GOES_HERE}}
Example: 'templates/my-nav.html'
The template, if specified, is pre-processed using _.template.
loadDefaults
Use this option to disable any of the four scripts angular
, angularAnimate
, marked
, and prettify
(google) which are loaded by default. This would give the user the ability to disable any scripts if they are using methods outside of regular angular/animate loading like browserify.
Example usage:
var opts = loadDefaults: angularAnimate: false
Options for Sections
glob
[required] glob pattern of files to parse for documentation comments.
title
[default] name of the section. Set the title for the section in the documentation app.
api
[default] true
Set the name for the section in the documentation app.