Commitid

.gitignore

@@ -8,3 +8,4 @@ npm-debug.log
 
 docs-ghpages
 bower_components
+.vscode/

lib/builder.js

@@ -292,6 +292,7 @@ var BuilderContext = {
         debug('skipping class ' + clazz.name);
         return;
       } 
+      clazz.members.sort(compareEntries);
       if (clazz.isEnum) {
         clazz.type = 'enums';
         enums.push(clazz);
@@ -300,6 +301,8 @@ var BuilderContext = {
         classes.push(clazz);
       }
     });
+    classes.sort(compareEntries);
+    enums.sort(compareEntries);
     opts.meta.classes = classes;
     opts.meta.enums = enums;
     return opts;
@@ -325,6 +328,28 @@ var BuilderContext = {
         mod.type = 'modules';
         mod.submodules = _.sortBy(submodules, 'name');
       }
+      if (mod.classes.length > 0) {
+        mod.hasClasses = true;
+        var classes = [];
+        var enums = [];
+        _.each(mod.classes, function (obj) {
+          if (obj.isEnum) {
+            enums.push(obj);
+          }
+          else {
+            classes.push(obj);
+          }
+        }); 
+        classes.sort(compareEntries);
+        enums.sort(compareEntries);
+        mod.classes = classes;
+        mod.enums = enums;
+      } else {
+        mod.hasClasses = false;
+      }
+      if (mod.members) {
+        mod.members.sort(compareEntries);
+      }
     });
     opts.meta.modules = _.sortBy(modules, 'name');
     return opts;
@@ -634,7 +659,7 @@ var BuilderContext = {
     var view = new DocView(locals.meta);
     view.base = '.';
     var html = this.render('index', view, locals);
-    var filename = this.options.markdown ? '/readme.md' : '/index.html';
+    var filename = this.options.markdown ? '/index.md' : '/index.html';
     var dest = this.options.dest + filename;
 
     debug('Start writing index.html');
@@ -710,6 +735,7 @@ var BuilderContext = {
       locals.meta.modules,
       function (mod) {
         mod.globals = locals.meta;
+        mod.enums = locals.meta.enums;
         var view = new DocView(mod, null, '../');
         var dest = path.join(self.options.dest, 'modules', mod.name + self.extname);
         view.base = '..';
@@ -729,6 +755,19 @@ var BuilderContext = {
 var emitter = new EventEmitter();
 BuilderContext = _.extend(BuilderContext, emitter);
 
+// sorting entries
+function compareEntries (a, b) {
+  var nameA = a.name.toLowerCase();
+  var nameB = b.name.toLowerCase();
+  if (nameA < nameB) {
+    return -1;
+  }
+  if (nameA > nameB) {
+    return 1;
+  }
+  return 0;
+}
+
 /**
  * Function to link an external type uses `NATIVES` object
  * @method NATIVES_LINKER

lib/firedoc.js

@@ -85,6 +85,16 @@ function Firedoc (config) {
   if (fs.existsSync(cwd + '/yuidoc.json')) {
     pkg = require(cwd + '/yuidoc.json');
     firedocOptions = pkg.options;
+    // change the default branch (master) to commit id. 
+    var myPath = __dirname.replace(/\\node_modules\\.+/, '');
+    myPath = path.resolve(myPath, './../engine');
+    var command = spawn('git', ['log','--format="%H"', '-n' ,'1'], {
+        cwd: myPath,
+    });
+    command.stdout.on('data', function (data) {
+      firedocOptions.sourceURL.branch = data.toString().trim().replace(/"/g, '');
+    });
+
     delete pkg.options;
   } else if (fs.existsSync(cwd + '/package.json')) {
     pkg = require(cwd + '/package.json');

lib/helpers.js

@@ -47,7 +47,7 @@ exports.crossLink = function oncrossLink (item, options) {
     _.each(parts, function (i) {
       p.push(this._parseCrossLink.call(this, i));
     }, this);
-    str = p.join(' | ');
+    str = p.join(' | ');
   } else {
     var ctx = '';
     if (typeof options.fn === 'function') {
@@ -110,3 +110,20 @@ exports.shouldShowInherit = function shouldShowInherit (item, options) {
     return options.inverse(this);
   }
 };
+
+exports.getSourceFile = function getSourceFile (item, options) {
+  var sourceURL = this.options.sourceURL;
+  var org = sourceURL.org, repo = sourceURL.repo, branch = sourceURL.branch;
+  var path = require('path');
+  var relativePath = path.relative(path.join(this.options.paths[0], repo), item).replace(/\\/g, '/');
+  var baseStr = `https://github.com/${org}/${repo}/blob/${branch}/` + relativePath;
+  return baseStr;
+};
+
+exports.getVersion = function getVersion () {
+  return this.options.version;
+};
+
+exports.encodeName = function encodeName (item, options) {
+  return encodeURI(item);
+};

lib/locals.js

@@ -220,6 +220,9 @@ var Locals = {
     html = html.replace(/<pre><code>/g, '<pre class="code prettyprint"><code>\n');
     // TODO(Yorkie): request to underscore, this is not working with &#39;
     html = html.replace(/&#39;/g, '\'');
+    if (this.options.markdown) {
+      html = html.replace(/&#(\d+);/g, function (m, p) { return String.fromCharCode(p); });
+    }
     return _.unescape(html);
   },
 
@@ -233,6 +236,13 @@ var Locals = {
   markdown: function (data) {
     var self = this;
     if (this.options.markdown) {
+      if (data.indexOf('{{#crossLink') > -1) {
+        var regex = /({{#crossLink\w*\s".*"}}.*{{\/crossLink\w*}})/g;
+        var result = data.replace(regex, function(match) {
+          return (Handlebars.compile(match))({});
+        });
+        return result;
+      }
       return data;
     }
     var html = _.unescape(md.render(data || ''));
@@ -265,6 +275,10 @@ var Locals = {
     if (mod) {
       if (!_.isArray(mod.classes)) mod.classes = [];
       mod.classes.push(clazz);
+      if (clazz.isEnum) {
+        // for markdown template checking whether should render enum section
+        mod.hasEnum = true;
+      }
     }
     return clazz;
   },
@@ -342,7 +356,7 @@ var Locals = {
     }
 
     if (this.options.markdown) {
-      member.markdownLink = utils.markdownLink(member.itemtype + ':' + member.name);
+      member.markdownLink = utils.markdownLink(member.name);
     }
     if (member.example) {
       if (!_.isArray(member.example)) {

lib/utils.js

@@ -373,7 +373,7 @@ exports.localize = localize;
 function markdownLink (str) {
   return str
     .replace(/[:,]/g, '-')
-    .replace(/[\s\(\)\[\]=]/g, '')
+    .replace(/[\s\(\)\[\]=_]/g, '')
     .toLowerCase();
 }
 exports.markdownLink = markdownLink;

package.json

@@ -102,7 +102,9 @@
   },
   "scripts": {
     "docs": "make docs",
-    "test": "make test.nocoverage"
+    "test": "make test.nocoverage",
+    "build-api": "node ./bin/firedoc.js build -M --lang zh",
+    "build-api-en": "node ./bin/firedoc.js build -M --lang en"    
   },
   "preferGlobal": "true",
   "licenses": [

themes/markdown/layouts/main.mdt

@@ -1,14 +1 @@
-
-{{#if globals.project.name}}
-# {{globals.project.name}} {{globals.project.version}}
-{{else}}
-# Fireball Engine API
-{{/if}}
-
-{{#if project.description}}
-{{project.description}}
-{{else}}
-Fireball is the game engine for the future.
-{{/if}}
-
 {{> layout_content}}

themes/markdown/partials/attrs.mdt

@@ -7,7 +7,7 @@
 {{#if extended_from}}
 > Inherited from `{{extended_from}}`
 {{/if}}
-Defined in `{{{file}}}:{{{line}}}`
+Defined in [{{getSourceFile file}}:{{{line}}}]({{getSourceFile file}}#L{{{line}}})
 {{/if}}
 
 {{#if deprecationMessage}}

themes/markdown/partials/class.mdt

@@ -1,11 +1,11 @@
-### `{{name}}` Class
+## `{{name}}` Class
 
 {{#if extends}}
-Extends `{{extends}}`
+Extends [`{{extends}}`]({{extends}}.md)
 {{/if}}
 
 {{#if foundAt}}
-Defined in: [{{{file}}}:{{{line}}}](../files/{{{file}}}.js)
+Defined in: [{{getSourceFile file}}:{{{line}}}]({{getSourceFile file}}#L{{{line}}})
 {{/if}}
 
 {{#if module}}

themes/markdown/partials/enum.mdt

@@ -5,7 +5,7 @@ Extends `{{extends}}`
 {{/if}}
 
 {{#if foundAt}}
-Defined in: [{{{file}}}:{{{line}}}](../files/{{{file}}}.js)
+Defined in: [{{getSourceFile file}}:{{{line}}}]({{getSourceFile file}}#L{{{line}}})
 {{/if}}
 
 {{#if module}}

themes/markdown/partials/events.mdt

@@ -5,7 +5,7 @@ Extends `{{extends}}`
 {{/if}}
 
 {{#if foundAt}}
-Defined in: [{{{file}}}:{{{line}}}]({{foundAt}})
+Defined in: [{{getSourceFile file}}:{{{line}}}]({{getSourceFile file}}#L{{{line}}})
 {{/if}}
 
 {{#if module}}

themes/markdown/partials/index.mdt

@@ -1,23 +1,31 @@
+# Index
 
-{{#if enums}}
-### Enums
-{{#enums}}
-{{#if is_enum}}
-- [`{{name}}`](enums/{{name}}.md) from [{{module}}](modules/{{module}}.md)
-{{/if}}
-{{/enums}}
+Cocos Creator v{{getVersion}}
+
+Welcome to Cocos Creator JavaScript engine API reference. You can search anything in top left search filed.
+
+All enums and classes are under `cc` module if not specified otherwise.
+
+{{#if modules}}
+### Module
+
+{{#modules}}
+- [`{{name}}`](modules/{{encodeName name}}.md)
+{{/modules}}
 {{/if}}
 
 {{#if classes}}
 ### Classes
+
 {{#classes}}
 - [`{{name}}`](classes/{{name}}.md) from [{{module}}](modules/{{module}}.md)
 {{/classes}}
 {{/if}}
 
-{{#if modules}}
-### Module
-{{#modules}}
-- [`{{name}}`](modules/{{name}}.md)
-{{/modules}}
+{{#if enums}}
+### Enums
+
+{{#enums}}
+- [`{{name}}`](enums/{{name}}.md) from [{{module}}](modules/{{module}}.md)
+{{/enums}}
 {{/if}}

themes/markdown/partials/items-index.mdt

@@ -38,40 +38,4 @@
   - [`{{name}}`](#{{markdownLink}}) {{{description}}}
 {{/members.events}}
 
-{{/if}}
-
-{{#if members.inherited}}
-
-### Inherited members
-
-##### Properties
-
-{{#members.inherited.properties}}
-- [`{{name}}`](#{{markdownLink}})
-{{/members.inherited.properties}}
-
-##### Attributes
-
-{{#members.inherited.attributes}}
-- [`{{name}}`](#{{markdownLink}})
-{{/members.inherited.attributes}}
-
-##### Methods
-
-{{#members.inherited.methods}}
-- [`{{methodName}}`](#{{markdownLink}})
-{{/members.inherited.methods}}
-
-##### Events
-
-{{#members.inherited.events}}
-- [`{{name}}`](#{{markdownLink}})
-{{/members.inherited.events}}
-
-{{/if}}
-
-{{#if children}}
-
-### Inheritance tree
-
 {{/if}}

themes/markdown/partials/method.mdt

@@ -12,7 +12,7 @@
 | Extends | `{{extended_from}}` |
   {{/if}}
 {{/if}}
-| Defined | [{{{file}}}:{{{line}}}]({{foundAt}}) |
+| Defined | [{{getSourceFile file}}:{{{line}}}]({{getSourceFile file}}#L{{{line}}}) |
 {{#if deprecationMessage}}
 | Deprecated | {{deprecationMessage}} |
 {{/if}}
@@ -44,6 +44,7 @@
 {{/if}}
 
 {{#example}}
-**Examples**
+##### Example
+
 {{{.}}}
 {{/example}}