automatic documentation to ionic-site

circle.yml

@@ -0,0 +1,27 @@
+machine:
+  node:
+    version: 4.1.0
+  ruby:
+    version: 2.1.2
+
+general:
+  branches:
+    only:
+      - master # ignore PRs and branches
+
+dependencies:
+ pre:
+   - ./scripts/docs/prepare.sh
+ cache_directories:
+   - "~/ionic-site" # cache ionic-site
+
+test:
+  override:
+    - npm test
+    - npm run build
+
+deployment:
+ staging:
+   branch: master
+   commands:
+     - ./scripts/docs/deploy.sh

gulpfile.js

@@ -0,0 +1,3 @@
+var gulp = require('gulp');
+
+require('./scripts/docs/gulp-tasks')(gulp);

package.json

@@ -38,6 +38,11 @@
   },
   "devDependencies": {
     "@types/node": "^6.0.41",
+    "cpr": "^2.0.0",
+    "dgeni": "^0.4.2",
+    "dgeni-packages": "^0.16.0",
+    "gulp": "^3.9.1",
+    "semver": "^5.3.0",
     "tslint": "^3.10.2",
     "tslint-ionic-rules": "*",
     "typescript": "^2.0.3"

scripts/config.json

@@ -0,0 +1,5 @@
+{
+  "sitePath": "../ionic-site",
+  "clientDocsDir": "docs/v2/storage",
+  "docsDest": "../ionic-site/docs/v2/storage"
+}

scripts/docs/deploy.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+
+ARG_DEFS=(
+  #"--version-name=(.*)"
+)
+
+echo "##### "
+echo "##### docs/deploy.sh"
+echo "#####"
+
+function init {
+  cd ..
+  SITE_PATH=$(readJsonProp "config.json" "sitePath")
+  SITE_DIR=$SITE_PATH
+  DOCS_DEST=$(readJsonProp "config.json" "docsDest")
+}
+
+function run {
+  cd ..
+  VERSION=$(readJsonProp "package.json" "version")
+
+  # process new docs
+  if [ -d "$DOCS_DEST" ]; then
+    rm -R $DOCS_DEST
+  fi
+  ./node_modules/.bin/gulp docs
+
+  # CD in to the site dir to commit updated docs
+  cd $SITE_DIR
+
+  CHANGES=$(git status --porcelain)
+
+  # if no changes, don't commit
+  if [[ "$CHANGES" == "" ]]; then
+    echo "-- No changes detected for the following commit, docs not updated."
+    echo "https://github.com/driftyco/$CIRCLE_PROJECT_REPONAME/commit/$CIRCLE_SHA1"
+  else
+    git add -A
+    git commit -am "Automated build of cloud client v$VERSION driftyco/$CIRCLE_PROJECT_REPONAME@$CIRCLE_SHA1"
+    # in case a different commit was pushed to ionic-site during doc/demo gen,
+    # try to rebase around it before pushing
+    git fetch
+    git rebase
+
+    git push origin master
+
+    echo "-- Updated docs for $VERSION_NAME succesfully!"
+  fi
+
+}
+
+source $(dirname $0)/../utils.sh.inc

scripts/docs/dgeni-config.js

@@ -0,0 +1,183 @@
+var Package = require('dgeni').Package;
+var jsdocPackage = require('dgeni-packages/jsdoc');
+var nunjucksPackage = require('dgeni-packages/nunjucks');
+var typescriptPackage = require('./typescript-package');
+var linksPackage = require('./links-package');
+var gitPackage = require('dgeni-packages/git');
+var path = require('path');
+var semver = require('semver');
+var fs = require('fs');
+var _ = require('lodash');
+var config = require('../config.json');
+
+// Define the dgeni package for generating the docs
+module.exports = function(currentVersion) {
+
+  return new Package('ionic-cloud-client-docs',
+                     [jsdocPackage, nunjucksPackage, typescriptPackage,
+                      linksPackage, gitPackage])
+
+  .processor(require('./processors/latest-version'))
+  // .processor(require('./processors/index-page'))
+  .processor(require('./processors/jekyll'))
+  .processor(require('./processors/remove-private-members'))
+  .processor(require('./processors/hide-private-api'))
+  .processor(require('./processors/collect-inputs-outputs'))
+  .processor(require('./processors/parse-returns-object'))
+
+// for debugging docs
+// .processor(function test(){
+//   return {
+//
+//     $runBefore: ['rendering-docs'],
+//     $process: function(docs){
+//       docs.forEach(function(doc){
+//         if (doc.name == "Searchbar"){
+//           console.log(doc.input);
+//           doc.members.forEach(function(method){
+//             if (method.name === "load") {
+//               console.log(method);
+//             }
+//           })
+//         }
+//       })
+//     }
+//   }
+// })
+
+  .config(function(log) {
+    log.level = 'error'; //'silly', 'debug', 'info', 'warn', 'error'
+  })
+
+  .config(function(renderDocsProcessor, computePathsProcessor, versionInfo) {
+    try {
+      versions = fs.readdirSync(
+        path.resolve(__dirname, '../../' + config.docsDest + '/')
+      ).filter(semver.valid);
+    } catch (e) {
+      versions = [];
+    }
+
+    // new version, add it to the versions list
+    if (currentVersion != 'nightly' && !_.contains(versions, currentVersion)) {
+      versions.unshift(currentVersion);
+    }
+
+    // sort by version so we can find latest
+    versions.sort(semver.rcompare);
+    // add nightly if it isn't in the list
+    !_.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;
+      // Instead set nightly as docs root
+      var folder = version == 'nightly' ? '' : version;
+      return {
+        href: path.join('/' + config.clientDocsDir, folder),
+        folder: folder,
+        name: version
+      };
+    });
+
+    var versionData = {
+      list: versions,
+      current: _.find(versions, {name: currentVersion}),
+      latest: _.find(versions, {name: latestVersion}) || _.first(versions)
+    };
+
+    renderDocsProcessor.extraData.version = versionData;
+    renderDocsProcessor.extraData.versionInfo = versionInfo;
+
+    computePathsProcessor.pathTemplates = [{
+      docTypes: ['class', 'var', 'function', 'let'],
+      getOutputPath: function(doc) {
+        // strip ionic from path root
+        var docPath = doc.fileInfo.relativePath.replace(/^src\//, '');
+        // remove filename since we have multiple docTypes per file
+        docPath = docPath.substring(0, docPath.lastIndexOf('/') + 1);
+        docPath += doc.name + '/index.md';
+        var path = config.clientDocsDir + '/' +  docPath;
+        path = path.replace(process.cwd() + '/src', '');
+        return path;
+      }
+    }];
+  })
+
+  //configure file reading
+  .config(function(readFilesProcessor, readTypeScriptModules) {
+
+    // Don't run unwanted processors since we are not using the normal file reading processor
+    readFilesProcessor.$enabled = false;
+    readFilesProcessor.basePath = path.resolve(__dirname, '../..');
+
+    readTypeScriptModules.basePath = path.resolve(
+      path.resolve(__dirname, '../..')
+    );
+    readTypeScriptModules.sourceFiles = [
+      'src/storage.ts'
+    ];
+  })
+
+  .config(function(parseTagsProcessor) {
+    parseTagsProcessor.tagDefinitions = parseTagsProcessor.tagDefinitions
+      .concat(require('./tag-defs/tag-defs'));
+  })
+
+  // .config(function(parseTagsProcessor) {
+  //   // We actually don't want to parse param docs in this package as we are getting the data out using TS
+  //   parseTagsProcessor.tagDefinitions.forEach(function(tagDef) {
+  //     console.log(tagDef);
+  //     if (tagDef.name === 'param') {
+  //       tagDef.docProperty = 'paramData';
+  //       tagDef.transforms = [];
+  //     }
+  //   });
+  // })
+
+  // Configure links
+  .config(function(getLinkInfo) {
+    getLinkInfo.useFirstAmbiguousLink = false;
+  })
+
+  // Configure file writing
+  .config(function(writeFilesProcessor) {
+    writeFilesProcessor.outputFolder  = config.sitePath;
+  })
+
+  // Configure rendering
+  .config(function(templateFinder, templateEngine) {
+
+    // Nunjucks and Angular conflict in their template bindings so change the Nunjucks
+    // Also conflict with Jekyll
+    templateEngine.config.tags = {
+      variableStart: '<$',
+      variableEnd: '$>',
+      blockStart: '<@',
+      blockEnd: '@>',
+      commentStart: '<#',
+      commentEnd: '#>'
+    };
+
+    // add custom filters to nunjucks
+    templateEngine.filters.push(
+      require('./filters/capital'),
+      require('./filters/code'),
+      require('./filters/dump')
+    );
+
+    templateFinder.templateFolders.unshift(
+      path.resolve(__dirname, 'templates')
+    );
+
+    // Specify how to match docs to templates.
+    templateFinder.templatePatterns = [
+      '${ doc.template }',
+      '${ doc.docType }.template.html',
+      'common.template.html'
+    ];
+  });
+
+};

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/filters/dump.js

@@ -0,0 +1,6 @@
+module.exports = {
+  name: 'dump',
+  process: function(obj) {
+    console.log(obj);
+  }
+};

scripts/docs/gulp-tasks.js

@@ -0,0 +1,15 @@
+var config = require('../config.json');
+var projectPackage = require('../../package.json');
+module.exports = function(gulp) {
+  gulp.task('docs', [], function() {
+    var Dgeni = require('dgeni');
+    var semver = require('semver');
+    try {
+      var ionicPackage = require('./dgeni-config')(projectPackage.version);
+      var dgeni = new Dgeni([ionicPackage]);
+      return dgeni.generate();
+    } catch (err) {
+      console.log(err.stack);
+    }
+  });
+}

scripts/docs/links-package/index.js

@@ -0,0 +1,12 @@
+var Package = require('dgeni').Package;
+
+module.exports = new Package('links', [])
+
+.factory(require('./inline-tag-defs/link'))
+.factory(require('dgeni-packages/links/services/getAliases'))
+.factory(require('dgeni-packages/links/services/getDocFromAlias'))
+.factory(require('./services/getLinkInfo'))
+
+.config(function(inlineTagProcessor, linkInlineTagDef) {
+  inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
+});

scripts/docs/links-package/inline-tag-defs/link.js

@@ -0,0 +1,33 @@
+var INLINE_LINK = /(\S+)(?:\s+([\s\S]+))?/;
+
+/**
+ * @dgService linkInlineTagDef
+ * @description
+ * Process inline link tags (of the form {@link some/uri Some Title}), replacing them with HTML anchors
+ * @kind function
+ * @param  {Object} url   The url to match
+ * @param  {Function} docs error message
+ * @return {String}  The html link information
+ *
+ * @property {boolean} relativeLinks Whether we expect the links to be relative to the originating doc
+ */
+module.exports = function linkInlineTagDef(getLinkInfo, createDocMessage, log) {
+  return {
+    name: 'link',
+    description: 'Process inline link tags (of the form {@link some/uri Some Title}), replacing them with HTML anchors',
+    handler: function(doc, tagName, tagDescription) {
+
+      // Parse out the uri and title
+      return tagDescription.replace(INLINE_LINK, function(match, uri, title) {
+
+        var linkInfo = getLinkInfo(uri, title, doc);
+
+        if ( !linkInfo.valid ) {
+          log.warn(createDocMessage(linkInfo.error, doc));
+        }
+
+        return "<a href='" + linkInfo.url + "'>" + linkInfo.title + "</a>";
+      });
+    }
+  };
+};