gulp-material-docs v1.2.1
Gulp Material Docs
A gulp plugin to create Material Design inspired documentation
Table of Contents
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 theoptions
object with yourangular
andangular-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
Clone the repository from GitHub
git clone https://github.com/dougiefresh49/gulp-material-docs.git
Install the dependencies
npm install && bower install
Build release or development version
Release
gulp default
Development
gulp dev
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