api doc formatting

scripts/docs/dgeni-config.js

@@ -76,7 +76,7 @@ module.exports = function(currentVersion){
                // strip ionic from path root
                .replace(/^ionic\//, '')
                // replace extension with .html
-               .replace(/\.\w*$/, '.html');
+               .replace(/\.\w*$/, '.md');
     }
   }];
 })
@@ -128,6 +128,12 @@ module.exports = function(currentVersion){
     commentEnd: '#>'
   };
 
+  // add custom filters to nunjucks
+  templateEngine.filters.push(
+    require('./filters/capital'),
+    require('./filters/code')
+  );
+
   templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates'));
 
   // Specify how to match docs to templates.

scripts/docs/filters/capital.js

@@ -0,0 +1,7 @@
+module.exports = {
+  name: 'capital',
+  process: function(str) {
+    str || (str = '');
+    return str.charAt(0).toUpperCase() + str.substring(1);
+  }
+};

scripts/docs/filters/code.js

@@ -0,0 +1,25 @@
+var encoder = new require('node-html-encoder').Encoder();
+
+function code(str, inline, lang) {
+  // Encode any HTML entities in the code string
+  str = encoder.htmlEncode(str, true);
+
+  // If a language is provided then attach a CSS class to the code element
+  lang = lang ? ' class="lang-' + lang + '"' : '';
+
+  str = '<code' + lang + '>' + str + '</code>';
+
+  // If not inline then wrap the code element in a pre element
+  if ( !inline ) {
+    str = '<pre>' + str + '</pre>';
+  }
+
+  return str;
+};
+
+module.exports = {
+  name: 'code',
+  process: function(str, lang) {
+    return code(str, true, lang);
+  }
+};

scripts/docs/templates/common.template.html

@@ -1,7 +1,7 @@
 ---
 <@ include "lib/yaml.template.html" @>
 title: "<@ if doc.docType == "directive" @><$ doc.name | dashCase $><@ else @><$ doc.name $><@ endif @>"
-header_sub_title: "<$ doc.docType $> in module <$ doc.module $>"
+header_sub_title: "<$ doc.docType | capital $> in module <$ doc.module $>"
 doc: "<$ doc.name $>"
 docType: "<$ doc.docType $>"
 ---
@@ -17,6 +17,54 @@ docType: "<$ doc.docType $>"
   <a href="https://github.com/<$ versionInfo.gitRepoInfo.owner $>/<$ versionInfo.gitRepoInfo.repo $>/tree/master/<$ doc.fileInfo.relativePath $>#L<$ doc.location.start.line+1 $>-L<$ doc.location.end.line+1 $>"><$ doc.fileInfo.relativePath $> (line <$ doc.location.start.line+1 $>)</a>
 <@- endmacro -@>
 
+<@ macro paramTable(params, isDirective) @>
+<table class="table" style="margin:0;">
+  <thead>
+    <tr>
+      <th><@ if isDirective @>Attr<@ else @>Param<@ endif @></th>
+      <th>Type</th>
+      <th>Details</th>
+    </tr>
+  </thead>
+  <tbody>
+    <@ for param in params @>
+    <tr>
+      <td>
+        <$ param.name $>
+        <@ if param.alias @>| <$ param.alias $><@ endif @>
+        <@ if param.type.optional @><div><em>(optional)</em></div><@ endif @>
+      </td>
+      <td>
+        <$ typeList(param.typeList) $>
+      </td>
+      <td>
+        <$ param.description | marked $>
+        <@ if param.default @><p><em>(default: <$ param.default $>)</em></p><@ endif @>
+      </td>
+    </tr>
+    <@ endfor @>
+  </tbody>
+</table>
+<@ endmacro @>
+
+<@- macro functionSyntax(fn) @>
+<@- set sep = joiner(', ') -@>
+<code><$ fn.name $>(<@- for param in fn.params @><$ sep() $>
+  <@- if param.type.optional @>[<@ endif -@>
+  <$ param.name $>
+  <@- if param.type.optional @>]<@ endif -@>
+  <@ endfor @>)</code><@ if fn.alias @><small>(alias: <$ fn.alias $>)</small><@ endif @>
+<@ endmacro -@>
+
+<@ macro typeList(types) -@>
+  <@ set separator = joiner("|") @>
+  <@ for type in types @><$ separator() $><$ type | code $><@ endfor @>
+<@- endmacro -@>
+
+<@- macro typeInfo(fn) -@>
+<$ typeList(fn.typeList) $> <$ fn.description $>
+<@- endmacro -@>
+
 <@ block body @>
 <div class="improve-docs">
   <a href='http://github.com/driftyco/ionic/tree/master/<$ doc.relativePath $>#L<$ doc.startingLine $>'>
@@ -72,6 +120,34 @@ defined in <$ githubViewLink(doc) $>
 <@ endfor @>
 <@ endif -@>
 
+<@- if doc.members @>
+## Members
+<@- for method in doc.members @>
+
+<div id="<$ method.name $>"></div>
+<h2>
+  <$ functionSyntax(method) $>
+</h2>
+
+<$ 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 -@>
+
+<!-- Angular doc template
 <@- if doc.constructorDoc or doc.members.length -@>
 <h2>Members</h2>
 
@@ -96,6 +172,7 @@ defined in <$ githubViewLink(doc) $>
 
 <@ endif @><@ endfor @>
 <@- endif -@>
+-->
 
 <@ endblock @>
 <@ endblock @>