docs/template/tizen/common.js

   1 // Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
   2 exports.path = {};
   3 exports.path.getFileNameWithoutExtension = getFileNameWithoutExtension;
   4 exports.path.getDirectoryName = getDirectoryName;
   5
   6 exports.getHtmlId = getHtmlId;
   7
   8 exports.getViewSourceHref = getViewSourceHref;
   9 exports.getImproveTheDocHref = getImproveTheDocHref;
  10 exports.processSeeAlso = processSeeAlso;
  11
  12 exports.isAbsolutePath = isAbsolutePath;
  13 exports.isRelativePath = isRelativePath;
  14
  15 function getFileNameWithoutExtension(path) {
  16     if (!path || path[path.length - 1] === '/' || path[path.length - 1] === '\\') return '';
  17     var fileName = path.split('\\').pop().split('/').pop();
  18     return fileName.slice(0, fileName.lastIndexOf('.'));
  19 }
  20
  21 function getDirectoryName(path) {
  22     if (!path) return '';
  23     var index = path.lastIndexOf('/');
  24     return path.slice(0, index + 1);
  25 }
  26
  27 function getHtmlId(input) {
  28     if (!input) return '';
  29     return input.replace(/\W/g, '_');
  30 }
  31
  32 // Note: the parameter `gitContribute` won't be used in this function
  33 function getViewSourceHref(item, gitContribute, gitUrlPattern) {
  34     if (!item || !item.source || !item.source.remote) return '';
  35     return getRemoteUrl(item.source.remote, item.source.startLine - '0' + 1, null, gitUrlPattern);
  36 }
  37
  38 function getImproveTheDocHref(item, gitContribute, gitUrlPattern) {
  39     if (!item) return '';
  40     if (!item.documentation || !item.documentation.remote) {
  41         return getNewFileUrl(item, gitContribute, gitUrlPattern);
  42     } else {
  43         return getRemoteUrl(item.documentation.remote, item.documentation.startLine + 1, gitContribute, gitUrlPattern);
  44     }
  45 }
  46
  47 function processSeeAlso(item) {
  48     if (item.seealso) {
  49         for (var key in item.seealso) {
  50             addIsCref(item.seealso[key]);
  51         }
  52     }
  53     item.seealso = item.seealso || null;
  54 }
  55
  56 function isAbsolutePath(path) {
  57     return /^(\w+:)?\/\//g.test(path);
  58 }
  59
  60 function isRelativePath(path) {
  61     if (!path) return false;
  62     return !exports.isAbsolutePath(path);
  63 }
  64
  65 var gitUrlPatternItems = {
  66     'github': {
  67         // HTTPS form: https://github.com/{org}/{repo}.git
  68         // SSH form: git@github.com:{org}/{repo}.git
  69         // generate URL: https://github.com/{org}/{repo}/blob/{branch}/{path}
  70         'testRegex': /^(https?:\/\/)?(\S+\@)?(\S+\.)?github\.com(\/|:).*/i,
  71         'generateUrl': function (gitInfo) {
  72             var url = normalizeGitUrlToHttps(gitInfo.repo);
  73             url = getRepoWithoutGitExtension(url);
  74             url += '/blob' + '/' + gitInfo.branch + '/' + gitInfo.path;
  75             if (gitInfo.startLine && gitInfo.startLine > 0) {
  76                 url += '/#L' + gitInfo.startLine;
  77             }
  78             return url;
  79         },
  80         'generateNewFileUrl': function (gitInfo, uid) {
  81             var url = normalizeGitUrlToHttps(gitInfo.repo);
  82             url = getRepoWithoutGitExtension(url);
  83             url += '/new';
  84             url += '/' + gitInfo.branch;
  85             url += '/' + getOverrideFolder(gitInfo.apiSpecFolder);
  86             url += '/new?filename=' + getHtmlId(uid) + '.md';
  87             url += '&value=' + encodeURIComponent(getOverrideTemplate(uid));
  88             return url;
  89         }
  90     },
  91     'vso': {
  92         // HTTPS form: https://{user}.visualstudio.com/{org}/_git/{repo}
  93         // SSH form: ssh://{user}@{user}.visualstudio.com:22/{org}/_git/{repo}
  94         // generated URL under branch: https://{user}.visualstudio.com/{org}/_git/{repo}?path={path}&version=GB{branch}
  95         // generated URL under detached HEAD: https://{user}.visualstudio.com/{org}/_git/{repo}?path={path}&version=GC{commit}
  96         'testRegex': /^(https?:\/\/)?(ssh:\/\/\S+\@)?(\S+\.)?visualstudio\.com(\/|:).*/i,
  97         'generateUrl': function (gitInfo) {
  98             var url = normalizeGitUrlToHttps(gitInfo.repo);
  99             var branchPrefix = /[0-9a-fA-F]{40}/.test(gitInfo.branch) ? 'GC' : 'GB';
 100             url += '?path=' + gitInfo.path + '&version=' + branchPrefix + gitInfo.branch;
 101             if (gitInfo.startLine && gitInfo.startLine > 0) {
 102                 url += '&line=' + gitInfo.startLine;
 103             }
 104             return url;
 105         },
 106         'generateNewFileUrl': function (gitInfo, uid) {
 107             return '';
 108         }
 109     }
 110 }
 111
 112 function getRepoWithoutGitExtension(repo) {
 113     if (repo.substr(-4) === '.git') {
 114         repo = repo.substr(0, repo.length - 4);
 115     }
 116     return repo;
 117 }
 118
 119 function normalizeGitUrlToHttps(repo) {
 120     var pos = repo.indexOf('@');
 121     if (pos == -1) return repo;
 122     return 'https://' + repo.substr(pos + 1).replace(/:[0-9]+/g, '').replace(/:/g, '/');
 123 }
 124
 125 function getNewFileUrl(item, gitContribute, gitUrlPattern) {
 126     // do not support VSO for now
 127     if (!item.source) {
 128         return '';
 129     }
 130
 131     var gitInfo = getGitInfo(gitContribute, item.source.remote);
 132     if (!gitInfo.repo || !gitInfo.branch || !gitInfo.path) {
 133         return '';
 134     }
 135
 136     var patternName = getPatternName(gitInfo.repo, gitUrlPattern);
 137     if (!patternName) return patternName;
 138     return gitUrlPatternItems[patternName].generateNewFileUrl(gitInfo, item.uid);
 139 }
 140
 141 function getRemoteUrl(remote, startLine, gitContribute, gitUrlPattern) {
 142     var gitInfo = getGitInfo(gitContribute, remote);
 143     if (!gitInfo.repo || !gitInfo.branch || !gitInfo.path) {
 144         return '';
 145     }
 146
 147     var patternName = getPatternName(gitInfo.repo, gitUrlPattern);
 148     if (!patternName) return '';
 149
 150     gitInfo.startLine = startLine;
 151     return gitUrlPatternItems[patternName].generateUrl(gitInfo);
 152 }
 153
 154 function getGitInfo(gitContribute, gitRemote) {
 155     // apiSpecFolder defines the folder contains overwrite files for MRef, the default value is apiSpec
 156     var defaultApiSpecFolder = 'apiSpec';
 157
 158     var result = {};
 159     if (gitContribute && gitContribute.apiSpecFolder) {
 160         result.apiSpecFolder = gitContribute.apiSpecFolder;
 161     } else {
 162         result.apiSpecFolder = defaultApiSpecFolder;
 163     }
 164     mergeKey(gitContribute, gitRemote, result, 'repo');
 165     mergeKey(gitContribute, gitRemote, result, 'branch');
 166     mergeKey(gitContribute, gitRemote, result, 'path');
 167
 168     return result;
 169
 170     function mergeKey(source, sourceFallback, dest, key) {
 171         if (source && source.hasOwnProperty(key)) {
 172             dest[key] = source[key];
 173         } else if (sourceFallback && sourceFallback.hasOwnProperty(key)) {
 174             dest[key] = sourceFallback[key];
 175         }
 176     }
 177 }
 178
 179 function getPatternName(repo, gitUrlPattern) {
 180     if (gitUrlPattern && gitUrlPattern.toLowerCase() in gitUrlPatternItems) {
 181         return gitUrlPattern.toLowerCase();
 182     } else {
 183         for (var p in gitUrlPatternItems) {
 184             if (gitUrlPatternItems[p].testRegex.test(repo)) {
 185                 return p;
 186             }
 187         }
 188     }
 189     return '';
 190 }
 191
 192 function getOverrideFolder(path) {
 193     if (!path) return "";
 194     path = path.replace('\\', '/');
 195     if (path.charAt(path.length - 1) == '/') path = path.substring(0, path.length - 1);
 196     return path;
 197 }
 198
 199 function getOverrideTemplate(uid) {
 200     if (!uid) return "";
 201     var content = "";
 202     content += "---\n";
 203     content += "uid: " + uid + "\n";
 204     content += "summary: '*You can override summary for the API here using *MARKDOWN* syntax'\n";
 205     content += "---\n";
 206     content += "\n";
 207     content += "*Please type below more information about this API:*\n";
 208     content += "\n";
 209     return content;
 210 }
 211
 212 function addIsCref(seealso) {
 213     if (!seealso.linkType || seealso.linkType.toLowerCase() == "cref") {
 214         seealso.isCref = true;
 215     }
 216 }