From 8b8f1e147fb025a6cf62d2c237ab9c791a684481 Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Fri, 8 Mar 2019 13:29:06 +0000 Subject: [PATCH] [ADF-4190] Fixed bad auto-generated URLs (#4413) * [ADF-4190] Tool + config updates to fix Typedoc issues * [ADF-4190] Added missing AppDefinitionRepresentation link --- lib/tsconfig.json | 5 ++++ package.json | 4 ++-- tools/doc/doctool.config.json | 36 +++++++++++++++++++++++++++- tools/doc/tools/typeLinker.js | 19 ++++++++++----- tools/doc/tools/typeLinker.ts | 17 +++++++++---- tools/doc/yamlTemplates/template.ejs | 2 +- 6 files changed, 68 insertions(+), 15 deletions(-) diff --git a/lib/tsconfig.json b/lib/tsconfig.json index ae00dc34f5..4766aea730 100644 --- a/lib/tsconfig.json +++ b/lib/tsconfig.json @@ -49,5 +49,10 @@ "strictMetadataEmit": false, "skipTemplateCodegen": true, "preserveWhitespaces": false + }, + "typedocOptions": { + "json": "docs/docs.json", + "exclude": ["**/*.spec.ts", "node_modules"], + "ignoreCompilerErrors": true } } diff --git a/package.json b/package.json index 1745d85c5e..fd2cf6af0a 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "author": "Alfresco Software, Ltd.", "main": "./index.js", "scripts": { - "docbuild": "node node_modules/typedoc/bin/typedoc --tsconfig lib/tsconfig.json --json docs/docs.json --exclude '**/*.spec.ts' --ignoreCompilerErrors && node tools/doc/buildYamlSourceInfo.js docs/docs.json && node ./tools/doc/docProcessor.js", + "docbuild": "node node_modules/typedoc/bin/typedoc --tsconfig lib/tsconfig.json && node tools/doc/buildYamlSourceInfo.js docs/docs.json && node ./tools/doc/docProcessor.js", "prepublishOnly": "npm run build-lib", "markdownlint": "markdownlint ./docs", "stylelint": "stylelint ./**/*.scss --config stylelint-config.json", @@ -168,7 +168,7 @@ "tsickle": "^0.34.0", "tslib": "^1.9.0", "tslint": "5.9.1", - "typedoc": "^0.11.1", + "typedoc": "^0.14.2", "typescript": "^3.1.6", "unist-util-select": "^2.0.0", "url-join": "^4.0.0", diff --git a/tools/doc/doctool.config.json b/tools/doc/doctool.config.json index 93d688adb3..e09b5e7ff2 100644 --- a/tools/doc/doctool.config.json +++ b/tools/doc/doctool.config.json @@ -42,25 +42,59 @@ "TemplateRef": "https://angular.io/api/core/TemplateRef", "Observable": "http://reactivex.io/documentation/observable.html", "Subject": "http://reactivex.io/documentation/subject.html", + "AppsDefinitionApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api-legacy/activiti-rest-api/src/api/AppsDefinitionApi.ts", "AppDefinitionRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-activiti-rest-api/docs/AppDefinitionRepresentation.md", + "ClassesApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/classes.api.ts", + "ContentApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/content.api.ts", + "DeletedNodeEntry": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/DeletedNodeEntry.md", "DeletedNodesPaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/DeletedNodesPaging.md", "DownloadBodyCreate": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/DownloadBodyCreate.md", "DownloadEntry": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/DownloadEntry.md", + "FavoritesApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/favorites.api.ts", "GroupMemberPaging": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/GroupMemberPaging.md", + "GroupsApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/groups.api.ts", "MinimalNode": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeMinimalEntry.md", "Node": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/Node.md", "NodeEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md", + "NodePaging": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/NodePaging.md", + "NodesApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/nodes.api.ts", + "PathElement": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/PathElement.md", + "PermissionElement": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/PermissionElement.md", + "PersonBodyCreate": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/model/personBodyCreate.ts", + "PeopleApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/people.api.ts", + "ProcessDefinitionRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/ProcessDefinitionRepresentation.md", "ProcessInstanceFilterRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/ProcessInstanceFilterRepresentation.md", + "ProcessInstanceQueryRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/ProcessInstanceQueryRepresentation.md", + "RatingEntry": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/RatingEntry.md", "RelatedContentRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-activiti-rest-api/docs/RelatedContentRepresentation.md", "RenditionEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionEntry.md", "RenditionPaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/RenditionPaging.md", + "RenditionsApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/renditions.api.ts", + "RequestPagination": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/search-rest-api/docs/RequestPagination.md", + "RestVariable": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/RestVariable.md", + "ResultListDataRepresentationUserProcessInstanceFilterRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/ResultListDataRepresentation%C2%ABUserProcessInstanceFilterRepresentation%C2%BB.md", + "SearchApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api-legacy/legacy.ts", + "SharedLinkEntry": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/SharedLinkEntry.md", + "SharedLinkPaging": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/SharedLinkPaging.md", + "SharedLinksApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/sharedlinks.api.ts", "SiteEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SiteEntry.md", + "SiteMemberPaging":"https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/SiteMemberPaging.md", "SitePaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md", + "SitesApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/sites.api.ts", "TagEntry": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/TagEntry.md", "TagPaging": "https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/TagPaging.md", + "TaskApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api-legacy/activiti-rest-api/docs/TaskApi.md", + "TaskUpdateRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/TaskUpdateRepresentation.md", + "UserInfo": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/UserInfo.md", "UserProcessInstanceFilterRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/UserProcessInstanceFilterRepresentation.md", - "UserRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/UserRepresentation.md" + "UserRepresentation": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/activiti-rest-api/docs/UserRepresentation.md", + "VersionsApi": "https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/api/versions.api.ts" }, + "linkOverrides": [ + "activiti", "auth", "authentication", "comment", "company", "core", "download", + "favorite", "file", "group", "pagination", "path", "person", "preference", + "rating", "rendition", "search", "site", "storage", "tag", "version" + ], "typeNameExceptions": { "activiti-alfresco.service": "ActivitiContentService", "auth-guard-bpm.service": "AuthGuardBpm", diff --git a/tools/doc/tools/typeLinker.js b/tools/doc/tools/typeLinker.js index 0eb645325f..2e78e159d8 100644 --- a/tools/doc/tools/typeLinker.js +++ b/tools/doc/tools/typeLinker.js @@ -1,5 +1,5 @@ "use strict"; -exports.__esModule = true; +Object.defineProperty(exports, "__esModule", { value: true }); var path = require("path"); var unist = require("../unistHelpers"); var ngHelpers = require("../ngHelpers"); @@ -11,6 +11,7 @@ var includedNodeTypes = [ var docFolder = path.resolve("docs"); var adfLibNames = ["core", "content-services", "insights", "process-services", "process-services-cloud", "extensions"]; var externalNameLinks; +var linkOverrides; function processDocs(mdCache, aggData, errorMessages) { initPhase(aggData, mdCache); var pathnames = Object.keys(mdCache); @@ -21,6 +22,10 @@ function processDocs(mdCache, aggData, errorMessages) { exports.processDocs = processDocs; function initPhase(aggData, mdCache) { externalNameLinks = aggData.config.externalNameLinks; + linkOverrides = {}; + aggData.config.linkOverrides.forEach(function (override) { + linkOverrides[override.toLowerCase()] = 1; + }); aggData.docFiles = {}; aggData.nameLookup = new SplitNameLookup(); /* @@ -286,7 +291,13 @@ function resolveTypeLink(aggData, docFilePath, text) { */ var classInfo = aggData.classInfo[possTypeName]; //if (ref && isLinkable(ref.kind)) { - if (classInfo) { + if (linkOverrides[possTypeName.toLowerCase()]) { + return ''; + } + else if (externalNameLinks[possTypeName]) { + return externalNameLinks[possTypeName]; + } + else if (classInfo) { var kebabName = ngHelpers.kebabifyClassName(possTypeName); var possDocFile = aggData.docFiles[kebabName]; //let url = "../../" + classInfo.sourcePath; @@ -297,9 +308,6 @@ function resolveTypeLink(aggData, docFilePath, text) { } return url; } - else if (externalNameLinks[possTypeName]) { - return externalNameLinks[possTypeName]; - } else { return ""; } @@ -317,7 +325,6 @@ function fixRelDocUrl(docPathFrom, docPathTo) { var relDocPathFrom = docPathFrom.substring(docPathFrom.indexOf('docs')); var docPathSegments = relDocPathFrom.split(/[\\\/]/); var dotPathPart = ''; - console.log("Fixing: " + docPathFrom + " " + docPathTo); for (var i = 0; i < (docPathSegments.length - 2); i++) { dotPathPart += '../'; } diff --git a/tools/doc/tools/typeLinker.ts b/tools/doc/tools/typeLinker.ts index 71aa4d80dc..209f452468 100644 --- a/tools/doc/tools/typeLinker.ts +++ b/tools/doc/tools/typeLinker.ts @@ -20,6 +20,7 @@ const docFolder = path.resolve("docs"); const adfLibNames = ["core", "content-services", "insights", "process-services", "process-services-cloud", "extensions"]; let externalNameLinks; +let linkOverrides; export function processDocs(mdCache, aggData, errorMessages) { initPhase(aggData, mdCache); @@ -34,6 +35,12 @@ export function processDocs(mdCache, aggData, errorMessages) { function initPhase(aggData, mdCache) { externalNameLinks = aggData.config.externalNameLinks; + + linkOverrides = {}; + aggData.config.linkOverrides.forEach(override => { + linkOverrides[override.toLowerCase()] = 1; + }); + aggData.docFiles = {}; aggData.nameLookup = new SplitNameLookup(); @@ -346,7 +353,11 @@ function resolveTypeLink(aggData, docFilePath, text): string { let classInfo = aggData.classInfo[possTypeName]; //if (ref && isLinkable(ref.kind)) { - if (classInfo) { + if (linkOverrides[possTypeName.toLowerCase()]) { + return ''; + } else if (externalNameLinks[possTypeName]) { + return externalNameLinks[possTypeName]; + } else if (classInfo) { let kebabName = ngHelpers.kebabifyClassName(possTypeName); let possDocFile = aggData.docFiles[kebabName]; @@ -360,8 +371,6 @@ function resolveTypeLink(aggData, docFilePath, text): string { } return url; - } else if (externalNameLinks[possTypeName]) { - return externalNameLinks[possTypeName]; } else { return ""; } @@ -384,8 +393,6 @@ function fixRelDocUrl(docPathFrom: string, docPathTo: string) { let docPathSegments = relDocPathFrom.split(/[\\\/]/); let dotPathPart = ''; - console.log(`Fixing: ${docPathFrom} ${docPathTo}`); - for (let i = 0; i < (docPathSegments.length - 2); i++) { dotPathPart += '../'; } diff --git a/tools/doc/yamlTemplates/template.ejs b/tools/doc/yamlTemplates/template.ejs index 6431ce951b..f3702ff94d 100644 --- a/tools/doc/yamlTemplates/template.ejs +++ b/tools/doc/yamlTemplates/template.ejs @@ -3,7 +3,7 @@ items: name: <%= name %> fullName: <%= name %> source: - path: <%= 'lib/' + sources[0].fileName %> + path: <%= sources[0].fileName %> startLine: <%= sources[0].line %> children: <%_ if (typeof children !== "undefined") { -%>