Several updates to doc generation and presentation

craftyjs-site.css

@@ -6626,6 +6626,16 @@ h3 {
   border-bottom: 2px solid #CCC;
   margin-top: 2em;
 }
+.page-badge {
+  font-variant: small-caps;
+  background: #eee;
+  color: #aaa;
+  border-radius: 5px;
+  font-size: 12px;
+  padding: 2px;
+  vertical-align: middle;
+  margin-top: 5px;
+}
 /* The "back to top" links */
 .doc-top {
   float: right;

source/api-gen/clean-name.js

@@ -1,5 +1,6 @@
 var re = /[\.-]/g
+var omitRe = /[\(\)]/g
 
 module.exports = function cleanName(raw) {
-  return raw.replace(re, "-");
+  return raw.replace(re, "-").replace(omitRe, "");
 }

source/api-gen/doc-components.jsx

@@ -1,6 +1,10 @@
 var marked = require("marked");
 var hljs = require("highlight.js");
 var cleanName = require("./clean-name");
+var kindName = function(name, kind) {
+  return kind === "Method" ? name + "()" : name;
+}
+
 var githubRoot = "https://github.com/craftyjs/Crafty/blob/";
 
 
@@ -58,6 +62,17 @@ var ToC = React.createClass({
 
 })
 
+var TocLink = React.createClass({
+  render: function() {
+    var target = this.props.target;
+    var linkText = kindName(target.name, target.kind);
+    var href = cleanName(target.name) + ".html"; 
+    return <a href={href}>{linkText}</a>
+  }
+
+
+});
+
 var DocLink = React.createClass({
   render: function() {
     var target = this.props.target;
@@ -100,8 +115,8 @@ var DocLink = React.createClass({
 
 var Category = React.createClass({
   render: function() {
-    this.props.pages.sort(stringSort);
-    var pages = this.props.pages.map(function(page, index){return <li key={page}><DocLink target={page}/></li>});
+    this.props.pages.sort(nameSort);
+    var pages = this.props.pages.map(function(page, index){return <li key={page.name}><TocLink target={page}/></li>});
     return ( 
       <li className="category">
         {this.props.catName}
@@ -357,9 +372,11 @@ var Doclet = React.createClass({
   render: function() {
     var contents = this.props.data.contents;
     var pieces =  mapNodes(contents, this.props.page);
+    var partName = kindName(this.props.data.name, this.props.data.kind); 
+
     if (!this.props.top) {
       var link = <a href='#doc-nav' className='doc-top'>Back to top</a>
-      var header = <h2 className="doclet-header">{this.props.data.name}</h2>
+      var header = <h2 className="doclet-header">{partName}</h2>
     } else {
       var link = "";
       var header = "";
@@ -381,13 +398,21 @@ var SourceLink = React.createClass({
     var start = this.props.data.startLine;
     var end = this.props.data.endLine;
     var commit = this.props.data.commit;
-    var fileLocation = file +"#L" + start + "-" + end;
+    var fileLocation = file +"#L" + start + "-" + "L" + end;
     var target = githubRoot + commit + "/" + fileLocation;
     return <a href={target}>{fileLocation}</a>
   }
 
 })
 
+// properties before methods
+function partSort(a, b) {
+  if (a.kind != b.kind) {
+    return (a.kind == "method") ? 1 : -1
+  } else {
+    return nameSort(a, b);
+  }
+}
 
 
 function nameSort(a, b) {
@@ -413,34 +438,72 @@ var DocPage = React.createClass({
       return <div/>
     }
     var parts = page.parts;
-    parts.sort(nameSort);
+    parts.sort(partSort);
     var partlets = parts.map(function(part, index){return <Doclet key={index} data={part} top={false} page={page}/>});
-    var page_toc = parts.map( function(part, index){ return <li key={index}><InternalLink parent={page.main.name} target={part.name} value={part.name}/></li>});
+
+
+    var toc_mapper = function(part, index){ return <li key={index}><InternalLink parent={page.main.name} target={part.name} value={part.name} kind={part.kind}/></li>}
+    var method_toc = parts.filter(function(p){return p.kind === "Method"})
+      .map(toc_mapper);
+    var property_toc = parts.filter(function(p){return p.kind !== "Method"})
+      .map( toc_mapper);
+    //var page_toc = parts.map( function(part, index){ return <li key={index}><InternalLink parent={page.main.name} target={part.name} value={part.name} kind={part.kind}/></li>});
     if (!page.main){
       return <div/>
     }
     if (parts.length > 0) {
+      var pageTocPart = [];
+
+
+      if (property_toc.length > 0) {
+        pageTocPart.push(<SubSectionHeader>Properties</SubSectionHeader>);
+        pageTocPart.push(
+          <ul className = "page-toc">
+              {property_toc}
+          </ul>);
+      }
+
+      if (method_toc.length > 0) {
+        pageTocPart.push(<SubSectionHeader>Methods</SubSectionHeader>);
+        pageTocPart.push(
+          <ul className = "page-toc">
+              {method_toc}
+          </ul>);
+      }
+
       var bottomParts = 
         <div>
-          <SubSectionHeader>Methods and Properties</SubSectionHeader>
-          <ul className = "page-toc">
-            {page_toc}
-          </ul>
+          {pageTocPart}
           {partlets}
         </div>
     } else {
       var bottomParts = "";
     }
+    var header;
+    if (page.main.kind) {
+      header = <h1>{page.main.name}</h1> 
+    }
+    var pageName = kindName(page.main.name, page.main.kind);
     return (
       <div className="doc-page">
-        <h1>{page.main.name}</h1>
+        <h1>{pageName} <KindBadge kind={page.main.kind} /></h1>
         <Doclet data={page.main} page={page} top={true}/>
         {bottomParts}
       </div>
     )
   }
 })
 
+var KindBadge = React.createClass({
+  render: function() {
+    var kind = this.props.kind;
+    if (kind == "Component" || kind == "System" || kind == "Class") {
+      return <span className="page-badge">{kind}</span>
+    }
+    return <span/>;
+  }
+});
+
 var EventPage = React.createClass({
   render: function() {
     var parts = this.props.data;
@@ -477,6 +540,10 @@ var InternalLink = React.createClass({
       if (linkText.indexOf(this.props.parent) == 0 ) {
         linkText = linkText.replace(this.props.parent, "");
       }
+      var kind = this.props.kind;
+      if (kind === "Method") {
+        linkText += "()";
+      }
       return <a href={"#" + cleanTarget}>{linkText}</a>
     }
 });

source/api-gen/index-docs.js

@@ -17,7 +17,7 @@ function createIndex(blocks) {
     if (block.categories) {
       for (var j = 0; j < block.categories.length; j++) {
         if (block.name) {
-          cat(block.categories[j]).pages.push(block.name)
+          cat(block.categories[j]).pages.push({name: block.name, kind: block.kind})
         }
         comp(block.name).main = block;
       }

source/api-gen/server-side.jsx

@@ -21,7 +21,15 @@ var StaticPage = React.createClass({
 			if (page) {
 				var content = <DocPage page={page} dict={dict} />
 			} else {
-				var content = <div/>
+				var content = <div className="api-landing-page markdown">
+      <h1>Crafty API</h1>
+	  <p>This is Crafty's api documentation, with numerous topics arranged by category.  
+	  For a gentler introduction, try either</p>
+	  <ul>
+	  	<li>The <a href="../getting-started">quickstart guide</a></li>
+	  	<li>The <a href="../documentation">documentation overview</a></li>
+	  </ul>
+    </div>
 			}
 		}
 

source/less/doc-style.less

@@ -10,10 +10,20 @@
 @warning-light: lighten(@warning, 30%);
 
 /* Horizontal space between blocks*/
-.block-spacing {
+.block-spacing {  
   margin-top: 1em;
 }
 
+.badge(@color) {
+  font-variant: small-caps;
+  background: @color;
+  color: #aaa;
+  border-radius: 5px;
+  font-size: 12px;
+  padding: 2px;
+  vertical-align: middle;
+}
+
 
 
 /* Blocks offset by a large colored margin */
@@ -51,6 +61,11 @@ h1, h2, h3 {
   margin-top: 2em;
 }
 
+.page-badge {
+  .badge(#eee);
+  margin-top: 5px;
+}
+
 /* The "back to top" links */
 .doc-top {
   float: right;