Add feature to add injected items that documenter is not providing

Vitalius1 · Vitalius1 · commit 370ab055d4e8 · 2019-06-04T19:22:49.000-07:00
diff --git a/apps/api-documenter/.vscode/launch.json b/apps/api-documenter/.vscode/launch.json
@@ -0,0 +1,23 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+      {
+          "type": "node",
+          "request": "launch",
+          "name": "Example",
+          "program": "${workspaceFolder}/lib/start.js",
+          "cwd": "${workspaceFolder}/../../build-tests/api-documenter-test",
+          "args": [
+            "generate",
+            "--input-folder",
+            "etc",
+            "--output-folder",
+            "etc/yaml"
+          ],
+          "sourceMaps": true
+        },
+  ]
+}
diff --git a/apps/api-documenter/src/documenters/ExperimentalYamlDocumenter.ts b/apps/api-documenter/src/documenters/ExperimentalYamlDocumenter.ts
@@ -66,7 +66,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
                 ? this._findInlineTagByName(this._config.filterByInlineTag, apiItem.tsdocComment)
                 : undefined;
 
-                const tagContent: string | undefined =
+            const tagContent: string | undefined =
               docInlineTag && docInlineTag.tagContent && docInlineTag.tagContent.trim();
 
             if (tagContent && this._tocPointerMap[tagContent]) {
@@ -104,7 +104,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
   private _generateTocPointersMap(tocConfig: IYamlTocFile | IYamlTocItem): void {
     if (tocConfig.items) {
       for (const tocItem of tocConfig.items) {
-        if (tocItem.items && tocItem.items.length > 0) {
+        if (tocItem.items && tocItem.items.length > 0 && this._shouldNotIncludeInPointersMap(tocItem)) {
           this._generateTocPointersMap(tocItem);
         } else {
           // check for presence of the `catchAllCategory` config option
@@ -136,4 +136,12 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
     }
     return undefined;
   }
+
+  private _shouldNotIncludeInPointersMap(item: IYamlTocItem): boolean {
+    const { categoryNodes } = this._config;
+    if (categoryNodes && categoryNodes.length) {
+      return categoryNodes.indexOf(item.name) === -1;
+    }
+    return true;
+  }
 }
diff --git a/apps/api-documenter/src/documenters/IConfigFile.ts b/apps/api-documenter/src/documenters/IConfigFile.ts
@@ -23,12 +23,6 @@ export interface IConfigTableOfContents {
    */
   catchAllCategory?: string;
 
-  /**
-   * When loading more than one api.json files that might include the same API items,
-   * toggle either to show duplicates or not.
-   */
-  noDuplicateEntries?: boolean;
-
   /**
    * Toggle either sorting of the API items should be made based on category name presence
    * in the API item's name.
@@ -40,6 +34,11 @@ export interface IConfigTableOfContents {
    * that is present on them.
    */
   filterByInlineTag?: string;
+
+  /**
+   * Array of node names to which API items will be pushed when filtered
+   */
+  categoryNodes?: string[];
 }
 
 /**
diff --git a/build-tests/api-documenter-test/config/api-documenter.json b/build-tests/api-documenter-test/config/api-documenter.json
@@ -17,11 +17,17 @@
                 { "name": "DocClass1", "items": [] }
               ]
             },
-            { "name": "References", "items": [] }
+            {
+              "name": "References",
+              "items": [
+                { "name": "InjectedCustomItem", "uid": "customUrl" }
+              ]
+            }
           ]
         }
       ]
     },
+    "categoryNodes": ["References"],
     "catchAllCategory": "References",
     "noDuplicateEntries": true,
     "filterByApiItemName": false,
diff --git a/build-tests/api-documenter-test/etc/yaml/toc.yml b/build-tests/api-documenter-test/etc/yaml/toc.yml
@@ -25,6 +25,8 @@ items:
                 uid: api-documenter-test.IDocInterface4
       - name: References
         items:
+          - name: InjectedCustomItem
+            uid: customUrl
           - name: DocEnum
             uid: api-documenter-test.DocEnum
           - name: Generic

Original file line number	Diff line number	Diff line change
`@@ -17,11 +17,17 @@`
`17`	`17`	`{ "name": "DocClass1", "items": [] }`
`18`	`18`	`]`
`19`	`19`	`},`
`20`		`- { "name": "References", "items": [] }`
	`20`	`+ {`
	`21`	`+ "name": "References",`
	`22`	`+ "items": [`
	`23`	`+ { "name": "InjectedCustomItem", "uid": "customUrl" }`
	`24`	`+ ]`
	`25`	`+ }`
`21`	`26`	`]`
`22`	`27`	`}`
`23`	`28`	`]`
`24`	`29`	`},`
	`30`	`+ "categoryNodes": ["References"],`
`25`	`31`	`"catchAllCategory": "References",`
`26`	`32`	`"noDuplicateEntries": true,`
`27`	`33`	`"filterByApiItemName": false,`