Здесь я копаюсь во внутренностях gulpfiles.js foundation-docs и foundation-sites, открываю Supercollider, panini... Потом ытаюсь найти склад тем SassDoc Theme Boilerplate... Здесь штук 20 ссылок, галпфайлы, и даже readme c foundation-docs
foundation-docs
Supercollider A fancy documentation generator that can mash up documentation from multiple sources, such as SassDoc and JSDoc. Used by the Foundation family of frameworks.
Features
Combines Markdown, SassDoc data, and JSDoc data into compiled HTML pages.
Supports custom Markdown and Handlebars instances.
Can generate a search result list out of documentation items.
Can be extended to support other documentation generators.
gulp-docs Generates a JSON file of your documents. It uses an enhanced version of DSS to do this.
Since the stream returns a JSON file it allows you to determin what you want to do with it. You can output the JSON file or pair it with nunjucks or another template compiler.
Personally I use angularjs and just use it as a data file because it's much easer that way.
gulp-cache-bust Append a query string to your assets to bust that cache!
gulp-newer A Gulp plugin for passing through only those source files that are newer than corresponding destination files.
panini A super simple flat file generator for use with Gulp. It compiles a series of HTML pages using a common layout. These pages can also include HTML partials, external Handlebars helpers, or external data as JSON or YAML.
require-dir Node helper to require() directories. The directory's files are examined, and each one that can be require()'d is require()'d and returned as part of a hash from that file's basename to its exported contents.
Panini Talk Demo
inline-css This module takes html and inlines the CSS properties into the style attribute.
Pizza Pie Charts Pizza is a responsive pie, donut, bar, and line graph charting library based on the Snap SVG framework from Adobe. It focuses on easy integration via HTML markup and CSS instead of JavaScript objects, although you can pass JavaScript objects to Pizza as well.
SassDoc parses your source folder to grab documentation-specific comments. From there, it builds a data tree, that gets enhanced and filtered before being passed to the view. So you end up with a fully styled HTML document, like this:
SassDoc Theme Boilerplate So you want to build your own theme? You've come to the appropriate place. This is a blank theme so you can build yours based on this one, without too much hassle hopefully.
zurb
Bloodhound is the typeahead.js suggestion engine. Bloodhound is robust, flexible, and offers advanced functionalities such as prefetching, intelligent caching, fast lookups, and backfilling with remote data.
Responsive Web Design - Templates
Handlebars is largely compatible with Mustache templates. In most cases it is possible to swap out Mustache with Handlebars and continue using your current templates
gulp-dom Gulp plugin for generic DOM manipulation
gulp API docs Jump to: gulp.src | gulp.dest | gulp.task | gulp.watch
Компактный и простой gulpfile.js¶
Плагин require-dir позволяет размещать задачи (gulp.task) в отдельных файлах в папке:
requireDir('./gulp');
Это мне представляется менее громоздким, чем использовать Lazy подход с gulp-load-plugins (см. у И.Кантора), но, судя по описанию require-dir, в память загружается все и сразу... Так что код упрощается, а память загромождаются...
# %load F:\stradorusite\foundation\sites\foundation-sites\gulpfile.js
var gulp = require('gulp');
var browser = require('browser-sync');
var requireDir = require('require-dir');
var port = process.env.SERVER_PORT || 3000;
requireDir('./gulp');
// Builds the documentation and framework files
gulp.task('build', ['clean', 'copy', 'docs:all', 'sass', 'javascript']);
// Starts a BrowerSync instance
gulp.task('serve', ['build'], function(){
browser.init({server: './_build', port: port});
});
// Watch files for changes
gulp.task('watch', function() {
gulp.watch('docs/**/*', ['docs', browser.reload]);
gulp.watch(['docs/layout/*.html', 'docs/partials/*.html', 'docs/assets/partials/*.html'], ['docs:all', browser.reload]);
gulp.watch('scss/**/*', ['sass', browser.reload]);
gulp.watch(['docs/assets/scss/**/*', 'foundation-docs/scss/**/*'], ['sass:docs', browser.reload]);
gulp.watch('js/**/*', ['javascript:foundation', browser.reload]);
gulp.watch('docs/assets/js/**/*', ['javascript:docs', browser.reload]);
});
// Runs all of the above tasks and then waits for files to change
gulp.task('default', ['serve', 'watch']);
Содерожимое папки './gulp'¶
F:\stradorusite\foundation\sites\foundation-sites>dir gulp
Том в устройстве F имеет метку MYLINUXLIVE
Серийный номер тома: CE7F-8134
Содержимое папки F:\stradorusite\foundation\sites\foundation-sites\gulp
01.09.2016 13:37 <DIR> .
01.09.2016 13:37 <DIR> ..
01.09.2016 13:37 318 babel-error.js
01.09.2016 13:37 155 clean.js
01.09.2016 13:37 258 copy.js
01.09.2016 13:37 4 367 customizer.js
01.09.2016 13:37 5 440 deploy.js
01.09.2016 13:37 2 042 docs.js
01.09.2016 13:37 1 337 javascript.js
01.09.2016 13:37 683 lint.js
02.09.2016 18:28 1 943 sass.js
01.09.2016 13:37 1 154 test.js
10 файлов 17 697 байт
2 папок 655 020 032 байт свободно
F:\stradorusite\foundation\sites\foundation-sites>
Вот так выглядит файл из папки¶
Возьмем для примера самый "необычный" (для меня) - docs.js
# %load 'F:\stradorusite\foundation\sites\foundation-sites\gulp\docs.js'
var cacheBust = require('gulp-cache-bust');
var foundationDocs = require('foundation-docs');
var gulp = require('gulp');
var newer = require('gulp-newer');
var panini = require('panini');
var supercollider = require('supercollider');
var PANINI_CONFIG = {
root: 'docs/pages/',
layouts: 'docs/layout/',
partials: 'docs/partials/',
helpers: foundationDocs.handlebarsHelpers,
}
var SEARCH_SORT_ORDER = ['page', 'component', 'sass variable', 'sass mixin', 'sass function', 'js class', 'js function', 'js plugin option', 'js event'];
var SEARCH_PAGE_TYPES = {
'library': function(item) {
return !!(item.library);
}
}
supercollider
.config({
template: foundationDocs.componentTemplate,
marked: foundationDocs.marked,
handlebars: foundationDocs.handlebars,
keepFm: true,
quiet: false,
pageRoot: 'docs/pages',
data: {
repoName: 'foundation-sites',
editBranch: 'master'
}
})
.searchConfig({
extra: 'docs/search.yml',
sort: SEARCH_SORT_ORDER,
pageTypes: SEARCH_PAGE_TYPES
})
.adapter('sass')
.adapter('js');
// Assembles the layout, pages, and partials in the docs folder
gulp.task('docs', function() {
return gulp.src('docs/pages/**/*')
.pipe(newer({
dest: '_build',
ext: '.html'
}))
.pipe(supercollider.init())
.pipe(panini(PANINI_CONFIG))
.pipe(cacheBust())
.pipe(gulp.dest('_build'))
.on('finish', buildSearch);
});
gulp.task('docs:all', function() {
panini.refresh();
return gulp.src('docs/pages/**/*')
.pipe(supercollider.init())
.pipe(panini(PANINI_CONFIG))
.pipe(cacheBust())
.pipe(gulp.dest('_build'))
.on('finish', buildSearch);
});
function buildSearch() {
supercollider.buildSearch('_build/data/search.json', function() {});
}
gulp.task('docs:debug', ['docs:all'], function(cb) {
var output = JSON.stringify(supercollider.tree, null, ' ');
require('fs').writeFile('./_debug.json', output, cb);
});
А вот как выглядит плагин foundation-docs, который мы загружаем из gulp\docs.js¶
F:\stradorusite\foundation\sites\foundation-sites\node_modules\foundation-docs>dir
02.09.2016 15:51 <DIR> .
02.09.2016 15:51 <DIR> ..
02.09.2016 15:51 67 .npmignore
02.09.2016 15:52 3 225 README.md
02.09.2016 15:53 1 094 LICENSE
02.09.2016 15:54 392 index.js
02.09.2016 15:56 1 935 gulpfile.js
02.09.2016 15:56 <DIR> helpers
02.09.2016 15:58 63 .travis.yml
02.09.2016 15:59 <DIR> js
02.09.2016 16:03 <DIR> lib
02.09.2016 16:10 31 .babelrc
02.09.2016 16:10 <DIR> scss
02.09.2016 16:13 <DIR> templates
02.09.2016 16:13 <DIR> test
02.09.2016 16:15 7 318 package.json
8 файлов 14 125 байт
8 папок 655 024 128 байт свободно
F:\stradorusite\foundation\sites\foundation-sites\node_modules\foundation-docs>
# %load F:\stradorusite\foundation\sites\foundation-sites\node_modules\foundation-docs\gulpfile.js
var $ = require('gulp-load-plugins')();
var browser = require('browser-sync');
var docs = require('./index');
var gulp = require('gulp');
var panini = require('panini');
var supercollider = require('supercollider');
// Supercollider configuration
supercollider
.config({
template: 'templates/component.html',
marked: docs.marked,
handlebars: docs.handlebars
})
.searchConfig({})
.adapter('sass')
.adapter('js')
// Generates a documentation page
gulp.task('pages', function() {
panini.refresh();
return gulp.src('test/fixtures/*.md')
.pipe(supercollider.init())
.pipe(panini({
root: 'test/fixtures',
layouts: 'test/visual',
partials: 'test/visual/partials'
}))
.pipe(gulp.dest('test/visual/_build'))
.on('finish', function() {
browser.reload();
supercollider.buildSearch('test/visual/_build/data/search.json');
});
});
// Compiles documentation CSS
gulp.task('sass', function() {
return gulp.src('test/visual/docs.scss')
.pipe($.sass({
includePaths: [
'scss',
'node_modules/foundation-sites/scss',
'node_modules/motion-ui/src'
]
}).on('error', $.sass.logError))
.pipe($.autoprefixer({
browsers: ['last 2 versions', 'ie >= 9']
}))
.pipe(gulp.dest('test/visual/_build'))
.pipe(browser.reload({ stream: true }));
});
gulp.task('javascript', function() {
gulp.src('js/**/*.js')
.pipe($.concat('docs.js'))
.pipe(gulp.dest('test/visual/_build'));
});
// Creates a server and watches for file changes
gulp.task('default', ['pages', 'sass', 'javascript'], function() {
browser.init({
server: 'test/visual/_build'
});
gulp.watch(['text/fixtures/**/*', 'test/visual/**/*.html'], ['pages']);
gulp.watch(['scss/**/*', 'test/visual/docs.scss'], ['sass']);
gulp.watch(['js/**/*'], ['javascript']);
});
# %load F:\stradorusite\foundation\sites\foundation-sites\node_modules\foundation-docs\index.js
var path = require('path');
var TEMPLATE_PATH = path.join(__dirname, 'templates/component.html');
var HELPERS_PATH = path.join(__dirname, 'helpers');
module.exports = {
handlebars: require('./lib/handlebars'),
marked: require('./lib/marked'),
componentTemplate: path.relative(process.cwd(), TEMPLATE_PATH),
handlebarsHelpers: path.relative(process.cwd(), HELPERS_PATH)
}
# %load F:\stradorusite\foundation\sites\foundation-sites\node_modules\
# foundation-docs\templates\component.html
<article class="docs-component" id="docs-{{escape title}}">
<a href="#docs-menu" class="small secondary expanded button hide-for-medium">Jump to Nav</a>
{{> header}}
<hr>
{{!-- Start container for docs and table of contents --}}
<div class="row">
{{!-- Start container for docs --}}
<div class="large-9 columns" id="docs">
{{ docs }}
{{#if sass}}
<hr>
{{> sass-reference}}
{{/if}}
{{#if js}}
<hr>
{{> javascript-reference}}
{{/if}}
{{#if sass}}
<!-- <hr> -->
{{> building-blocks}}
{{/if}}
</div>
{{!-- End container for docs --}}
{{> table-of-contents}}
</div>
{{!-- End container for docs and table of contents --}}
</article>
# Содержимое папки F:\stradorusite\foundation\sites\foundation-sites\node_modules
# \foundation-docs\templates\partials
02.09.2016 16:13 <DIR> .
02.09.2016 16:13 <DIR> ..
02.09.2016 16:13 580 building-blocks.hbs
02.09.2016 16:13 1 195 header.hbs
02.09.2016 16:13 3 835 javascript-reference.hbs
02.09.2016 16:13 3 933 sass-reference.hbs
02.09.2016 16:13 407 table-of-contents.hbs
5 файлов 9 950 байт
2 папок 654 987 264 байт свободно
# %load F:\stradorusite\foundation\sites\foundation-sites\node_modules\foundation-docs\README.md
Foundation Docs¶
This is a set of HTML templates and JavaScript utilities shared by the documentation pages for the Foundation family of frameworks, including:
Table of Contents¶
Installation¶
This codebase isn't on npm, but this Git repository can be referenced in a package.json:
{
"dependencies": {
"foundation-docs": "zurb/foundation-docs"
}
}
JavaScript Usage¶
When you require() the foundation-docs library, you get access to a handful of JavaScript libraries, as well as file paths to HTML templates.
foundationDocs.handlebars¶
An instance of a custom Handlebars renderer with all the helpful functions we need to generate documentation.
foundationDocs.marked¶
An instance of a custom Marked renderer, which has two custom functions:
- When headings are written, an anchor icon is added to the left of the heading text.
- When code samples are written:
- If the language is
html_example, a live rendering of the HTML in the sample is added. - If the language is
inky_example, a live rendering of the HTML in the sample—within an iframe that loads the Ink CSS—is added.
- If the language is
foundationDocs.componentTemplate¶
A String path to the HTML template used for component pages. The general structure is:
- Title area
- Main docs (converted Markdown)
- Sass reference
- JavaScript reference
- Table of contents
The path is node_modules/foundation-docs/templates/component.html.
Sass Usage¶
The CSS used for the Foundation documentation is included as a series of Sass partials. Foundation and Motion UI must be loaded manually before it.
@import 'foundation';
@import 'motion-ui';
@include foundation-everything;
@include motion-ui-transitions;
@import 'foundation-docs';
Testing¶
There are two kinds of tests in the repository:
- Unit tests, which are run with Mocha.
- Visual tests, which are full HTML templates with all of the documentation UI elements.
Run npm test to run the test suite, as well as a BrowserSync server pointing to the visual tests. You can make changes to the HTML, Sass, or JavaScript of the library and see the changes refresh live. Use this test environment to make changes to the documentation template.
Testing with Foundation¶
To test with an actual framework's documentation, you can hook the two folders together using npm link.
Let's assume you have foundation-sites and foundation-docs in the same folder:
- sites/
- foundation-sites/
- foundation-docs/While inside of the foundation-sites/ folder, run npm link ../foundation-docs. Now Foundation's documentation will reference the changes you're making.
Посты чуть ниже также могут вас заинтересовать
Комментариев нет:
Отправить комментарий