npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gulp-ngdocs-components-stu

v1.0.0

Published

gulp plugin for angularjs documentation

Downloads

9

Readme

gulp-ngdocs-components

Gulp plugin for building AngularJS like documentation. This is inspired from grunt-ngdocs. This plugin supports angular 1.x components.

Setup

npm install gulp-ngdocs-components --save-dev

Usage

Create a ngdocs gulp task

gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs-components');
  return gulp.src('path/to/src/*.js')
    .pipe(gulpDocs.process())
    .pipe(gulp.dest('./docs'));
});

Create a ngdocs gulp task with options

gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs-components');
  var options = {
    scripts: ['../app.min.js'],
    html5Mode: true,
    startPage: '/api',
    title: "My Awesome Docs",
    image: "path/to/my/image.png",
    imageLink: "http://my-domain.com",
    titleLink: "/api"
  }
  return gulp.src('path/to/src/*.js')
    .pipe(gulpDocs.process(options))
    .pipe(gulp.dest('./docs'));
});

To use a different AngularJS version pass angular and angular-animate files in scripts.

gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs-components');
  var options = {
    /* pass both .min.js and .min.js.map files for angular and angular-animate */
    scripts: [
      'bower_components/angular/angular.min.js',
      'bower_components/angular/angular.min.js.map',
      'bower_components/angular-animate/angular-animate.min.js',
      'bower_components/angular-animate/angular-animate.min.js.map'
    ]
  }

  /*
  If you choose to use the remote links pass in the .min.js links for angular and angular-animate

  var options = {
    scripts: [
      'http://ajax.googleapis.com/ajax/libs/angularjs/<version>/angular.min.js',
      'http://ajax.googleapis.com/ajax/libs/angularjs/<version>/angular-animate.min.js'
    ]
  }
  */
  return gulp.src('path/to/src/*.js')
    .pipe(gulpDocs.process(options))
    .pipe(gulp.dest('./docs'));
});

If you would like to divide your documentation into different sections, use gulpDocs.sections instead of gulp.src.

gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs-components');
  var options = {
    //options
  }
  return gulpDocs.sections({
    api: {
      glob:['src/**/*.js', '!src/**/*.spec.js'],
      api: true,
      title: 'API Documentation'
    },
    tutorial: {
      glob: ['content/tutorial/*.ngdoc'],
      title: 'Tutorial'
    }
  }).pipe(gulpDocs.process(options)).pipe(gulp.dest('./docs'));
});

Serving index.html file

Opening index.html file via file:// protocol will cause a number of troubles. The easier way to avoid it is to run local server. As an options you can use gulp-connect

npm install gulp-connect
gulp.task('connect_ngdocs', function() {
var connect = require('gulp-connect');
  connect.server({
    root: 'docs',
    livereload: false,
    fallback: 'docs/index.html',
    port: 8083
  });
});

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 polyfill 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.module('rfx', []).directive('rAutogrow', function() {
  //some nice code
});

This fork of gulp-ngdocs supports .components()

In addition to controllers, services, direcives… now support components:

/**
* @ngdoc component
* @name app.component:guideItem
*
* @description
* This component shows cards using the item binding for his own building.
*
* @param {object}  item      A object with card data
 */

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 additional custom JS files are loaded to the app. This allows the live examples to use custom directives, services, etc. The documentation app works with AngularJS 1.2+ and 1.3+. If you include a different version of AngularJS, make sure to include angular-animate.js as well.

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.

Example usage:

var opts = {
  analytics: {
    account: 'UA-XXXXXX-YY',
    domainName: 'http://mywebpage.com/'
  }
};

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:

<header class="header">
  <div class="navbar">
    <ul class="nav">
      {{links to all the docs pages}}
    </ul>
    {{YOUR_NAV_TEMPLATE_GOES_HERE}}
  </div>
</header>

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.