Gulp Material Docs

A gulp plugin to create Material Design inspired documentation

Table of Contents

1. Why Material Docs?
2. Setup
3. Usage
4. Options
5. Demo
6. Building Material Docs Locally
7. Future Features

Why Material Docs?

gulp-material-docs document generator is a beautiful AND easy way to display your docs based on Google's Material Design Patterns.

gulp-material-docs built right on top of gulp-ngdocs but with an entirely rebuilt internals for optimized performance. See below for features supported and those that are coming soon.

Setup

npm install --save-dev gulp-material-docs

Usage

With two simple gulp tasks, you will have your beautiful docs ready to go

• Setup at the top of the gulpfile

var gulp = require('gulp'),
    materialDocs = require('gulp-material-docs'),
    inject = require('gulp-inject');

• The main task that makes the documents

gulp.task('docs:make', function() {
    var sections = {
        materialDocs: {
            // Files to load into the defined section
            glob: [
                'src/**/*module.js',
                'src/**/*config.js',
                'src/**/*.js',
                '!src/**/*spec.js'
            ],
            title: 'Website'
        }
    };
    var options = {
        html5Mode: false,
        title: "Gulp Material Docs",
        startPage: '/materialDocs',
        imageLink: "https://github.com/dougiefresh49/gulp-material-docs",
        titleLink: "/materialDocs"
    };
    return materialDocs
        .sections(sections)
        .pipe(materialDocs.make(options))
        .pipe(gulp.dest('docs/'));
});

• The inject task, which will inject the dependency files into the generated docs/index.html file

gulp.task('docs:inject', ['docs:make'], function() {
    // get the default list of sources to inject to the docs/index.html file
    var toInject = gulp.src(materialDocs.srcToInject('docs/'), { read: false });

    return gulp
        .src('docs/index.html')
        .pipe(inject(toInject, {ignorePath: 'docs', addRootSlash: false}))
        .pipe(gulp.dest('docs/'));
});

Supplying your own Angular Version

This is just as easy and is required if you are using node -version 3 and above

• In the main task, add the scripts list to the options object with your angular and angular-animate paths.

var options = {
        html5Mode: false,
        title: "Gulp Material Docs",
        startPage: '/materialDocs',
        scripts: [
            'bower_components/angular/angular.min.js',
            'bower_components/angular-animate/angular-animate.min.js'
        ],
        imageLink: "https://github.com/dougiefresh49/gulp-material-docs",
        titleLink: "/materialDocs"
    };

• In the inject step, simply pass the angular paths to srcToInject function link to source file for more details

var angularOptions = {
    angularPath: 'bower_components/angular/angular.min.js',
    ngAnimatePath: 'bower_components/angular-animate/angular-animate.min.js'
};

var toInject = gulp.src(materialDocs.srcToInject('docs/', angularOptions), { read: false });

Options

Most options supported by gulp-ngdocs are supported or will be in the future. See currently unsupported options for more details and Additional Options for new options not supported by gulp-ngdocs.

Currently Unsupported Options

[analytics] {object}

• Coming soon.

[discussions]

• Coming soon.

[bestMatch] {bool}

• Best match will always occur on submission of search form. Other results will still be visible in the left nav bar.

[navTemplate] {string}

Additional Options

[legal] {object}

• The legal object is a container for links / text in the footer of the left navbar.

var legal = {
  companyName: 'Some Company',
  privacyLink: 'http://www.google.com/intl/en/policies/privacy/'
  termsLink: 'http://www.google.com/intl/en/policies/terms/'
};

[nodeModulesDir] {string} default: node_modules/gulp-material-docs/

• The path to your node modules, relative to your gulpfile.js

Example: Given the folder structure...

| - config
| - dist
| - docs
| - node_modules
| - src
| - gulpfile.js

the default path will work

[favicon] {string} default: ''

• The path to your .ico file used for the title icon of the docs site.

Example: Given the folder structure...

| - config
| - dist
    | -- material-docs.ico
| - docs
| - src
    | -- app
    | -- assets
         | -- images
              | -- material-docs.ico

The favico path would be written as such

var faviconPath = 'dist/material-docs.ico'

OR

var faviconPath = 'src/assets/images/material-docs.ico'

Demo

A full working demo will be available soon. For now, check out the images below or simply follow the steps for Building Material Docs Locally.

Building Material Docs Locally

1. Clone the repository from GitHub

   git clone https://github.com/dougiefresh49/gulp-material-docs.git

2. Install the dependencies

   npm install && bower install

3. Build release or development version

   Release gulp default

   Development gulp dev

4. Run the Docs

   Open docs/index.html with a localhost server Note: local gulp serve task will be added in the future for easier development

Future Features

• add mode detailed styling for chapter content and ngdoc files
• add ability to change color scheme
• add ability for direct source link (docs to code)
• add ability to show type for property
• functions - public or private support