diff --git a/scripts/release/publish-docs-content.sh b/scripts/release/publish-docs-content.sh index 91b533efbe85..8322955be7d2 100755 --- a/scripts/release/publish-docs-content.sh +++ b/scripts/release/publish-docs-content.sh @@ -32,8 +32,9 @@ mkdir $repoPath/overview mkdir $repoPath/guides mkdir $repoPath/api mkdir $repoPath/examples +mkdir $repoPath/plunker -# Move api files over to $repoPath/api +# Copy api files over to $repoPath/api cp -r $docsPath/api/* $repoPath/api # Flatten the markdown docs structure and move it into $repoPath/overview @@ -52,7 +53,7 @@ do fi done -# Move guide files over to $repoPath/guides +# Copy guide files over to $repoPath/guides for filename in $overviewFiles* do if [ -f $filename ]; then @@ -60,9 +61,12 @@ do fi done -# Move highlighted examples into $repoPath +# Copy highlighted examples into $repoPath cp -r $examplesSource/* $repoPath/examples +# Copy example plunker assets +rsync -a $docsPath/plunker $repoPath/plunker + # Copies assets over to the docs-content repository. cp LICENSE $repoPath/ diff --git a/tools/gulp/tasks/docs.ts b/tools/gulp/tasks/docs.ts index efc95961d346..793d07162cc9 100644 --- a/tools/gulp/tasks/docs.ts +++ b/tools/gulp/tasks/docs.ts @@ -1,7 +1,7 @@ import {task, src, dest} from 'gulp'; import {Dgeni} from 'dgeni'; import * as path from 'path'; -import {HTML_MINIFIER_OPTIONS} from '../constants'; +import {DIST_ROOT, HTML_MINIFIER_OPTIONS, SOURCE_ROOT} from '../constants'; // There are no type definitions available for these imports. const markdown = require('gulp-markdown'); @@ -13,6 +13,8 @@ const htmlmin = require('gulp-htmlmin'); const hljs = require('highlight.js'); const dom = require('gulp-dom'); +const DIST_DOCS = path.join(DIST_ROOT, 'docs'); + // Our docs contain comments of the form `` which serve as placeholders where // example code should be inserted. We replace these comments with divs that have a // `material-docs-example` attribute which can be used to locate the divs and initialize the example @@ -46,8 +48,17 @@ const MARKDOWN_TAGS_TO_CLASS_ALIAS = [ 'code', ]; -task('docs', ['markdown-docs', 'highlight-docs', 'api-docs', 'minify-html-docs']); +/** Generate all docs content. */ +task('docs', [ + 'markdown-docs', + 'highlight-examples', + 'api-docs', + 'minified-api-docs', + 'plunker-example-assets', +]); + +/** Generates html files from the markdown overviews and guides. */ task('markdown-docs', () => { return src(['src/lib/**/*.md', 'guides/*.md']) .pipe(markdown({ @@ -67,7 +78,11 @@ task('markdown-docs', () => { .pipe(dest('dist/docs/markdown')); }); -task('highlight-docs', () => { +/** + * Creates syntax-highlighted html files from the examples to be used for the source view of + * live examples on the docs site. + */ +task('highlight-examples', () => { // rename files to fit format: [filename]-[filetype].html const renameFile = (path: any) => { const extension = path.extname.slice(1); @@ -81,18 +96,26 @@ task('highlight-docs', () => { .pipe(dest('dist/docs/examples')); }); +/** Generates API docs from the source JsDoc using dgeni. */ task('api-docs', () => { const docsPackage = require(path.resolve(__dirname, '../../dgeni')); const docs = new Dgeni([docsPackage]); return docs.generate(); }); -task('minify-html-docs', ['api-docs'], () => { +/** Generates minified html api docs. */ +task('minified-api-docs', ['api-docs'], () => { return src('dist/docs/api/*.html') .pipe(htmlmin(HTML_MINIFIER_OPTIONS)) .pipe(dest('dist/docs/api/')); }); +/** Copies example sources to be used as plunker assets for the docs site. */ +task('plunker-example-assets', () => { + src(path.join(SOURCE_ROOT, 'examples', '**/*')) + .pipe(dest(path.join(DIST_DOCS, 'plunker', 'examples'))); +}); + /** Updates the markdown file's content to work inside of the docs app. */ function transformMarkdownFiles(buffer: Buffer, file: any): string { let content = buffer.toString('utf-8');