diff --git a/scripts/docs/dgeni-config.js b/scripts/docs/dgeni-config.js index 957b126f57..9b50ab7029 100644 --- a/scripts/docs/dgeni-config.js +++ b/scripts/docs/dgeni-config.js @@ -9,6 +9,8 @@ var path = require('path'); // Define the dgeni package for generating the docs module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage, linksPackage, gitPackage]) +.processor(require('./processors/index-page')) + // for debugging docs // .processor(function test(){ // return { @@ -74,6 +76,7 @@ module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, ty // Specify how to match docs to templates. // In this case we just use the same static template for all docs templateFinder.templatePatterns = [ + '${ doc.template }', '${ doc.docType }.template.html', 'common.template.html' ] @@ -88,7 +91,7 @@ module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, ty }) // Configure ids and paths -.config(function(computeIdsProcessor, computePathsProcessor, versionInfo) { +.config(function(computeIdsProcessor, computePathsProcessor) { // computeIdsProcessor.idTemplates.push({ // docTypes: ['guide'], // getId: function(doc) { diff --git a/scripts/docs/processors/index-page.js b/scripts/docs/processors/index-page.js new file mode 100644 index 0000000000..9eabb857e6 --- /dev/null +++ b/scripts/docs/processors/index-page.js @@ -0,0 +1,18 @@ +module.exports = function indexPage() { + return { + name: 'index-page', + description: 'Create documentation index page', + version: 'nightly', + $runAfter: ['adding-extra-docs'], + $runBefore: ['extra-docs-added'], + $process: function(docs) { + docs.push({ + docType: 'index-page', + id: 'index-page', + currentVersion: this.version, + template: 'api_index.template.html', + outputPath: 'index.md' + }); + } + } +}; diff --git a/scripts/docs/processors/jekyll.js b/scripts/docs/processors/jekyll.js new file mode 100644 index 0000000000..05efd58e2f --- /dev/null +++ b/scripts/docs/processors/jekyll.js @@ -0,0 +1,23 @@ +var log = require('winston'); + +module.exports = { + name: 'jekyll', + runAfter: ['api-docs'], + runBefore: ['compute-path'], + description: 'Create jekyll includes', + process: function(docs, config) { + var currentVersion = config.versionData.current.name; + docs.push({ + template: 'api_menu.template.html', + outputPath: '_includes/api_menu.html' + }); + docs.push({ + template: 'api_menu_version.template.html', + outputPath: '_includes/api_menu_' + currentVersion + '.html' + }); + docs.push({ + template: 'api_version_select.template.html', + outputPath: '_includes/api_version_select.html' + }); + } +}; diff --git a/scripts/docs/processors/latest-version.js b/scripts/docs/processors/latest-version.js new file mode 100644 index 0000000000..15b6070042 --- /dev/null +++ b/scripts/docs/processors/latest-version.js @@ -0,0 +1,30 @@ +var copy = require('cpr').cpr; +var mkdirp = require('mkdirp'); +var path = require('canonical-path'); +var q = require('q'); + +module.exports = { + name: 'latest-version', + runAfter: ['write-files'], + description: 'Copy the latest version (that was compiled to docs/) into docs/versionName', + process: function(docs, config) { + var versionData = config.get('versionData'); + + var docsBase = path.join(config.get('rendering.outputFolder'), 'docs'); + var versionDir = path.join(docsBase, versionData.latest.name); + var latestDir = path.join(docsBase, 'api'); + + var deferred = q.defer(); + + mkdirp(versionDir, function() { + copy(latestDir, path.join(versionDir, 'api'), { + deleteFirst: true, + overwrite: true + }, function(err, files) { + deferred.resolve(docs); + }); + }); + + return deferred.promise; + } +}; diff --git a/scripts/docs/processors/version-data.js b/scripts/docs/processors/version-data.js new file mode 100644 index 0000000000..05ed9ff703 --- /dev/null +++ b/scripts/docs/processors/version-data.js @@ -0,0 +1,52 @@ +var _ = require('lodash'); +var fs = require('fs'); +var semver = require('semver'); +var path = require('canonical-path'); + +module.exports = { + name: 'version-data', + runBefore: ['reading-files'], + description: 'Expose version data to templates', + process: function(extraData, config) { + var basePath = config.get('basePath'); + var outputFolder = config.get('rendering.outputFolder'); + var currentVersion = config.get('currentVersion'); + + var docsBaseFolder = path.resolve(basePath, outputFolder, 'docs'); + + var versions; + try { + versions = fs.readdirSync(docsBaseFolder) + .filter(semver.valid) + .sort(semver.rcompare); + } catch(e) { + versions = []; + } + + !_.contains(versions, currentVersion) && versions.unshift(currentVersion); + !_.contains(versions, 'nightly') && versions.unshift('nightly'); + + //First semver valid version is latest + var latestVersion = _.find(versions, semver.valid); + versions = versions.map(function(version) { + //Latest version is in docs root + var folder = version == latestVersion ? '' : version; + return { + href: path.join('/', config.get('versionFolderBase') || '', folder), + folder: folder, + name: version + }; + }); + + var versionData = { + list: versions, + current: _.find(versions, { name: currentVersion }), + latest: _.find(versions, {name: latestVersion}) || _.first(versions) + }; + + config.set('rendering.contentsFolder', + path.join(config.get('versionFolderBase') || '', versionData.current.folder || '')); + config.set('versionData', versionData); + extraData.version = versionData; + } +}; diff --git a/scripts/docs/templates/api/api.template.html b/scripts/docs/templates/api/api.template.html new file mode 100644 index 0000000000..b371759d5f --- /dev/null +++ b/scripts/docs/templates/api/api.template.html @@ -0,0 +1,79 @@ +--- +<@ include "lib/yaml.template.html" @> +title: "<@ if doc.docType == "directive" @><$ doc.name | dashCase $><@ else @><$ doc.name $><@ endif @>" +header_sub_title: "<$ doc.docType | capital $> in module <$ doc.module $>" +doc: "<$ doc.name $>" +docType: "<$ doc.docType $>" +--- + +
+ + View Source + +   + + Improve this doc + +
+ +<@ block content @> + +<@ block header @> +

+<@ if doc.docType == "directive" @> + <$ doc.name | dashCase $> +<@ else @> + <$ doc.name $> +<@ endif @> +<@ if doc.parent @> +
+ + Child of <$ doc.parent $> + +<@ endif @> +<@ if doc.delegate @> +
+ + Delegate: <$ doc.delegate $> + +<@ endif @> +

+ +<@ if doc.codepen @> +{% include codepen.html id="<$ doc.codepen $>" %} +<@ endif @> +<@ endblock @> + +<@ block description @> +<$ doc.description $> +<@ endblock @> + +<@ if doc.deprecated @> +
+ Deprecated API + <$ doc.deprecated| marked $> +
+<@ endif @> + +<@ block dependencies @> +<@- if doc.requires @> +

Dependencies

+ +<@ endif -@> +<@ endblock @> + +<@ block additional @> +<@ endblock @> + +<@ block examples @> +<@- if doc.examples @> +

Example

+<@- for example in doc.examples -@> + <$ example | marked $> +<@- endfor -@> +<@ endif -@> +<@ endblock @> + +<@ endblock @> diff --git a/scripts/docs/templates/api/componentGroup.template.html b/scripts/docs/templates/api/componentGroup.template.html new file mode 100644 index 0000000000..5da50ab340 --- /dev/null +++ b/scripts/docs/templates/api/componentGroup.template.html @@ -0,0 +1,26 @@ +--- +<@ include "lib/yaml.template.html" @> +title: "<@ if doc.title @><$ doc.title $><@ elif doc.module @><$ doc.groupType | title $>s in module ionic<@ else @>Pages<@ endif @>" +header_sub_title: "<$ doc.components.length $> <$ doc.groupType $>s" +doc: "<$ doc.groupType $>" +docType: "<$ doc.groupType $>" +--- + +<@ block content @> + +<$ doc.description $> + + + + + + + <@ for page in doc.components @> + + + + + <@ endfor @> +
NameDescription
<$ page.id | link(page.name, page) $><$ page.description | firstParagraph | marked $>
+ +<@ endblock @> diff --git a/scripts/docs/templates/api/controller.template.html b/scripts/docs/templates/api/controller.template.html new file mode 100644 index 0000000000..f7c24b9b0b --- /dev/null +++ b/scripts/docs/templates/api/controller.template.html @@ -0,0 +1,9 @@ +<@ extends "api/object.template.html" @> + +<@ block related_components @> + <@ if doc.providerDoc -@> +
  • + - <$ doc.providerDoc.name $> +
    • + <@- endif @> +<@ endblock @> diff --git a/scripts/docs/templates/api/directive.template.html b/scripts/docs/templates/api/directive.template.html new file mode 100644 index 0000000000..475c7d6c42 --- /dev/null +++ b/scripts/docs/templates/api/directive.template.html @@ -0,0 +1,56 @@ +<@ include "lib/macros.html" -@> +<@ extends "api/api.template.html" @> + +<@ block additional @> + + <@ block usage @> +

    Usage

    + <@ if doc.usage @> +<$ doc.usage $> + <@ else @> + <@ if doc.restrict.element @> + + ```html + <<$ doc.name | dashCase $> + <@- for param in doc.params @> + <$ directiveParam(param.alias or param.name, param.type, '="', '"') $> + <@- endfor @>> + ... + > + ``` + <@ endif -@> + + <@- if doc.restrict.attribute -@> + + ```html + <<$ doc.element $> + <@- for param in doc.params @> + <$ directiveParam(param.name, param.type, '="', '"') $> + <@- endfor @>> + ... + > + ``` + <@ endif -@> + + <@- if doc.restrict.cssClass -@> + + ```html + <@ set sep = joiner(' ') @> + <<$ doc.element $> class=" + <@- for param in doc.params -@> + <$ sep() $><$ directiveParam(param.name, param.type, ': ', ';') $> + <@- endfor @>"> ... > + ``` + <@ endif -@> + + <@- endif @> + <@ endblock -@> + + + <@ if doc.params @> +

    API

    +<$ paramTable(doc.params, true) $> + <@ endif @> + + <@ include "lib/events.template.html" @> +<@ endblock @> diff --git a/scripts/docs/templates/api/filter.template.html b/scripts/docs/templates/api/filter.template.html new file mode 100644 index 0000000000..4465fb1b06 --- /dev/null +++ b/scripts/docs/templates/api/filter.template.html @@ -0,0 +1,26 @@ +<@ include "lib/macros.html" -@> +<@ extends "api/api.template.html" @> + +<@ block additional @> +

    Usage

    +

    In HTML Template Binding

    + <@ if doc.usage @> + <$ doc.usage | code $> + <@ else @> + <@ code -@> + {{ <$ doc.name $>_expression | <$ doc.name $> + <@- for param in doc.params @> : <$ param.name $><@ endfor -@> + }} + <@- endcode @> + <@ endif @> + +

    In JavaScript

    + <@ code -@> + <@- set sep = joiner(', ') -@> + $filter('<$ doc.name $>')(<@ for param in doc.params @><$ sep() $><$ param.name $><@ endfor -@>) + <@- endcode @> + + <$ paramTable(doc.params) $> + <@ include "lib/this.template.html" @> + <@ include "lib/returns.template.html" @> +<@ endblock @> diff --git a/scripts/docs/templates/api/function.template.html b/scripts/docs/templates/api/function.template.html new file mode 100644 index 0000000000..5de46698cc --- /dev/null +++ b/scripts/docs/templates/api/function.template.html @@ -0,0 +1 @@ +<@ extends "api/object.template.html" @> diff --git a/scripts/docs/templates/api/object.template.html b/scripts/docs/templates/api/object.template.html new file mode 100644 index 0000000000..c602ca6b7d --- /dev/null +++ b/scripts/docs/templates/api/object.template.html @@ -0,0 +1,28 @@ +<@ include "lib/macros.html" -@> +<@ extends "api/api.template.html" @> + +<@ block additional @> + +<@ if doc.usage @> +## Usage +<$ doc.usage $> +<@ endif @> + + <@ if doc.params or doc.returns or doc.this or doc.kind == 'function' -@> +

    Usage

    + <@ if doc.usage @> + <$ doc.usage $> + <@ else @> + <$ functionSyntax(doc) $> + <@ endif @> + + <$ paramTable(doc.params) $> + <@ include "lib/this.template.html" @> + <@ include "lib/returns.template.html" @> + <@- endif @> + + <@ include "lib/methods.template.html" @> + <@ include "lib/events.template.html" @> + <@ include "lib/properties.template.html" @> + +<@ endblock @> diff --git a/scripts/docs/templates/api/page.template.html b/scripts/docs/templates/api/page.template.html new file mode 100644 index 0000000000..5de46698cc --- /dev/null +++ b/scripts/docs/templates/api/page.template.html @@ -0,0 +1 @@ +<@ extends "api/object.template.html" @> diff --git a/scripts/docs/templates/api/provider.template.html b/scripts/docs/templates/api/provider.template.html new file mode 100644 index 0000000000..8d5946f5b5 --- /dev/null +++ b/scripts/docs/templates/api/provider.template.html @@ -0,0 +1,9 @@ +<@ extends "api/object.template.html" @> + +<@ block related_components @> + <@ if doc.serviceDoc -@> +
  • + - <$ doc.serviceDoc.name $> +
    • + <@- endif @> +<@ endblock @> diff --git a/scripts/docs/templates/api/service.template.html b/scripts/docs/templates/api/service.template.html new file mode 100644 index 0000000000..f7c24b9b0b --- /dev/null +++ b/scripts/docs/templates/api/service.template.html @@ -0,0 +1,9 @@ +<@ extends "api/object.template.html" @> + +<@ block related_components @> + <@ if doc.providerDoc -@> +
  • + - <$ doc.providerDoc.name $> +
    • + <@- endif @> +<@ endblock @> diff --git a/scripts/docs/templates/api/type.template.html b/scripts/docs/templates/api/type.template.html new file mode 100644 index 0000000000..5de46698cc --- /dev/null +++ b/scripts/docs/templates/api/type.template.html @@ -0,0 +1 @@ +<@ extends "api/object.template.html" @> diff --git a/scripts/docs/templates/api/utility.template.html b/scripts/docs/templates/api/utility.template.html new file mode 100644 index 0000000000..f7c24b9b0b --- /dev/null +++ b/scripts/docs/templates/api/utility.template.html @@ -0,0 +1,9 @@ +<@ extends "api/object.template.html" @> + +<@ block related_components @> + <@ if doc.providerDoc -@> +
  • + - <$ doc.providerDoc.name $> +
    • + <@- endif @> +<@ endblock @> diff --git a/scripts/docs/templates/api_index.template.html b/scripts/docs/templates/api_index.template.html new file mode 100644 index 0000000000..8718195463 --- /dev/null +++ b/scripts/docs/templates/api_index.template.html @@ -0,0 +1,17 @@ +--- +layout: "docs_api" +path: "" + +title: Javascript +header_sub_title: Extend Ionic even further with the power of AngularJS +searchable: false +--- + +# AngularJS Extensions + +Ionic is both a CSS framework and a Javascript UI library. Many components need Javascript in order to produce magic, though often components +can easily be used without coding through framework extensions such as our AngularIonic extensions. + +Ionic follows the View Controller pattern popularized in such frameworks as Cocoa Touch. In the View Controller pattern, we treat different sections of the interface as child Views or even child View Controllers that contain other views. View Controllers then "power" the Views inside of them to provide interaction and UI functionality. A great example is the Tab Bar View Controller which processes taps on a Tab Bar to switch between a set of viewable panes. + +Explore our API docs for detailed information on the View Controllers and Javascript utilities available in Ionic. diff --git a/scripts/docs/templates/api_menu.template.html b/scripts/docs/templates/api_menu.template.html new file mode 100644 index 0000000000..3751ab3e7e --- /dev/null +++ b/scripts/docs/templates/api_menu.template.html @@ -0,0 +1,14 @@ +<@ for ver in version.list @> + <@ if ver.name != version.latest.name @> + <@ if loop.first @> +{% if page.versionHref == "<$ ver.href $>" %} + <@ else @> +{% elsif page.versionHref == "<$ ver.href $>" %} + <@ endif @> + {% include api_menu_<$ ver.name $>.html %} + <@ endif @> +<@ endfor @> +<# make the last case always be to show latest version #> +{% else %} + {% include api_menu_<$ version.latest.name $>.html %} +{% endif %} diff --git a/scripts/docs/templates/api_menu_version.template.html b/scripts/docs/templates/api_menu_version.template.html new file mode 100644 index 0000000000..9cdf4b5f14 --- /dev/null +++ b/scripts/docs/templates/api_menu_version.template.html @@ -0,0 +1,629 @@ + + + + +
  • + + Action Sheet + + +
    • + + + +
  • + + Backdrop + + +
    • + + + +
  • + + Content + + +
    • + + + +
  • + + Form Inputs + + +
    • + + + +
  • + + Gestures and Events + + +
    • + + + +
  • + + Headers/Footers + + +
    • + + + +
  • + + Keyboard + + +
    • + + + +
  • + + Lists + + +
    • + + + +
  • + + Loading + + + +
    • + + + +
  • + + Modal + + +
    • + + + +
  • + + Navigation + + +
    • + + + +
  • + + Platform + + +
    • + + + +
  • + + Popover + + +
    • + + + +
  • + + Popup + + +
    • + + + +
  • + + Scroll + + +
    • + + + +
  • + + Side Menus + + +
    • + + + +
  • + + Slide Box + + +
    • + + + +
  • + + Spinner + + +
    • + + + +
  • + + Tabs + + +
    • + + + +
  • + + Tap & Click + +
    • + + + +
  • + + Utility + + +
    • diff --git a/scripts/docs/templates/api_version_select.template.html b/scripts/docs/templates/api_version_select.template.html new file mode 100644 index 0000000000..d7cde2d460 --- /dev/null +++ b/scripts/docs/templates/api_version_select.template.html @@ -0,0 +1,11 @@ + + + diff --git a/scripts/docs/templates/lib/events.template.html b/scripts/docs/templates/lib/events.template.html new file mode 100644 index 0000000000..00eeb7f568 --- /dev/null +++ b/scripts/docs/templates/lib/events.template.html @@ -0,0 +1,25 @@ +<@- if doc.events @> +

    Events

    + +<@ endif -@> diff --git a/scripts/docs/templates/lib/macros.html b/scripts/docs/templates/lib/macros.html new file mode 100644 index 0000000000..38ebb70070 --- /dev/null +++ b/scripts/docs/templates/lib/macros.html @@ -0,0 +1,54 @@ +<@ macro typeList(types) -@> + <@ set separator = joiner("|") @> + <@ for type in types @><$ separator() $><$ type | code $><@ endfor @> +<@- endmacro -@> + +<@ macro paramTable(params, isDirective) @> + + + + + + + + + + <@ for param in params @> + + + + + + <@ endfor @> + +
    <@ if isDirective @>Attr<@ else @>Param<@ endif @>TypeDetails
    + <$ param.name $> + <@ if param.alias @>| <$ param.alias $><@ endif @> + <@ if param.type.optional @>
    (optional)
    <@ endif @> +     		+ <$ typeList(param.typeList) $> + + <$ param.description | marked $> + <@ if param.default @>

    (default: <$ param.default $>)

    <@ endif @> +
    +<@ endmacro @> + + +<@- macro directiveParam(name, type, join, sep) @> + <@- if type.optional @>[<@ endif -@> + <$ name | dashCase $><$ join $><$ type.description $><$ sep $> + <@- if type.optional @>]<@ endif -@> +<@ endmacro -@> + +<@- macro functionSyntax(fn) @> +<@- set sep = joiner(', ') -@> +<$ fn.name $>(<@- for param in fn.params @><$ sep() $> + <@- if param.type.optional @>[<@ endif -@> + <$ param.name $> + <@- if param.type.optional @>]<@ endif -@> + <@ endfor @>)<@ if fn.alias @>(alias: <$ fn.alias $>)<@ endif @> +<@ endmacro -@> + +<@- macro typeInfo(fn) -@> +<$ typeList(fn.typeList) $> <$ fn.description $> +<@- endmacro -@> diff --git a/scripts/docs/templates/lib/methods.template.html b/scripts/docs/templates/lib/methods.template.html new file mode 100644 index 0000000000..1833f2cd2e --- /dev/null +++ b/scripts/docs/templates/lib/methods.template.html @@ -0,0 +1,26 @@ +<@- if doc.methods @> +## Methods +<@- for method in doc.methods @> + +
    +

    + <$ functionSyntax(method) $> +

    + +<$ method.description $> + +<@ if method.params @> +<$ paramTable(method.params) $> +<@ endif @> + +<@ if method.this @> +#### Method's `this` +<$ method.this $> +<@ endif @> + +<@ if method.returns @> +* Returns: <$ typeInfo(method.returns) $> +<@ endif @> + +<@ endfor -@> +<@- endif -@> diff --git a/scripts/docs/templates/lib/properties.template.html b/scripts/docs/templates/lib/properties.template.html new file mode 100644 index 0000000000..49378dd6ca --- /dev/null +++ b/scripts/docs/templates/lib/properties.template.html @@ -0,0 +1,14 @@ +<@- if doc.properties @> +

    Properties

    +<@- for property in doc.properties @> + +
    +*

    <$ typeList(property.returns.typeList) $> <$ property.name $>

    + + <$ property.returns.description $> + + <$ property.description $> + +<@ endfor -@> + +<@- endif -@> diff --git a/scripts/docs/templates/lib/returns.template.html b/scripts/docs/templates/lib/returns.template.html new file mode 100644 index 0000000000..a6d6d90c7e --- /dev/null +++ b/scripts/docs/templates/lib/returns.template.html @@ -0,0 +1,4 @@ +<@ if doc.returns -@> +

    Returns

    +<$ typeInfo(doc.returns) $> +<@- endif @> diff --git a/scripts/docs/templates/lib/this.template.html b/scripts/docs/templates/lib/this.template.html new file mode 100644 index 0000000000..04981c23ad --- /dev/null +++ b/scripts/docs/templates/lib/this.template.html @@ -0,0 +1,4 @@ +<@ if doc.this @> +

    Method's <@ code @>this<@ endcode @>

    +<$ doc.this | marked $> +<@ endif @> diff --git a/scripts/docs/templates/lib/yaml.template.html b/scripts/docs/templates/lib/yaml.template.html new file mode 100644 index 0000000000..18f4f592a5 --- /dev/null +++ b/scripts/docs/templates/lib/yaml.template.html @@ -0,0 +1,4 @@ +layout: "docs_api" +version: "<$ version.current.name $>" +versionHref: "<$ version.current.href $>" +path: "<$ doc.path $>"