feat(api): Add package markdown index file processor

Author: BrunnerLivio

compiler/api/index.ts

@@ -16,11 +16,21 @@ function typeScriptConfiguration(readTypeScriptModules: any, tsParser: any) {
   // API files are typescript
   readTypeScriptModules.basePath = PROJECT_ROOT;
   readTypeScriptModules.sourceFiles = PACKAGES_PATH;
+  readTypeScriptModules.hidePrivateMembers = true;
 }
 
-function readFilesConfiguration(readFilesProcessor: any) {
-  readFilesProcessor.$enabled = false;
+function readFilesConfiguration(readFilesProcessor: any, packageContentFileReader: any) {
   readFilesProcessor.basePath = PROJECT_ROOT;
+
+  readFilesProcessor.fileReaders.push(packageContentFileReader);
+
+  readFilesProcessor.sourceFiles = [
+    {
+      basePath: PROJECT_ROOT,
+      include: PROJECT_ROOT + '/**/PACKAGE.md',
+      fileReader: 'packageContentFileReader'
+    }
+  ];
 }
 
 function jsDocConfiguration(

compiler/api/processors/processPackages.ts

@@ -1,4 +1,5 @@
 import { byId } from '../util/byId';
+import { dirname } from 'canonical-path';
 
 function getPackageName(packageDoc) {
   const idParts = packageDoc.id.split('/').filter(p => p !== 'lib' && p !== 'src');
@@ -11,6 +12,18 @@ module.exports = function processPackages() {
     $runAfter: ['parseTagsProcessor', 'extractDecoratedClasses'],
     $runBefore: ['rendering-docs'],
     $process(docs: any[]) {
+      const packageContentFiles = {};
+
+      docs = docs.filter(doc => {
+        if (doc.docType === 'package-content') {
+          packageContentFiles[dirname(doc.fileInfo.filePath)] = doc;
+          return false;
+        } else {
+          return true;
+        }
+      });
+
+
       docs.forEach((doc, index) => {
         if (doc.docType === 'module') {
           // Convert the doc type from 'module' to 'package'
@@ -19,7 +32,7 @@ module.exports = function processPackages() {
 
           if (doc.exports) {
             const publicExports = doc.exports.filter(doc => !doc.privateExport);
-            doc.modules = publicExports.filter(doc => doc.docType === 'decorator').sort(byId);
+            doc.decorators = publicExports.filter(doc => doc.docType === 'decorator').sort(byId);
             doc.modules = publicExports.filter(doc => doc.docType === 'nestmodule').sort(byId);
             doc.classes = publicExports.filter(doc => doc.docType === 'class').sort(byId);
             doc.injectables = publicExports.filter(doc => doc.docType === 'injectable').sort(byId);
@@ -29,6 +42,15 @@ module.exports = function processPackages() {
             doc.pipes = publicExports.filter(doc => doc.docType === 'pipe').sort(byId);
             doc.types = publicExports.filter(doc => doc.docType === 'type-alias' || doc.docType === 'const').sort(byId);
           }
+
+          const readmeDoc = packageContentFiles[dirname(doc.fileInfo.filePath)];
+          if (readmeDoc) {
+            doc.shortDescription = readmeDoc.shortDescription;
+            doc.description = readmeDoc.description;
+            doc.see = readmeDoc.see;
+            doc.fileInfo = readmeDoc.fileInfo;
+          }
+
         }
       });
     }

compiler/api/readers/package-content.ts

@@ -15,11 +15,9 @@
 module.exports = function packageContentFileReader() {
   return {
     name: 'packageContentFileReader',
-    defaultPattern: /PACKAGE\.md$/,
-    getDocs: function(fileInfo) {
-
-      // We return a single element array because content files only contain one document
-      return [{docType: 'package-content', content: fileInfo.content, startingLine: 1}];
-    }
+    // defaultPattern: /PACKAGE\.md$/,
+    getDocs: fileInfo => [
+      { docType: 'package-content', content: fileInfo.content, startingLine: 1 }
+    ]
   };
-};
+};

compiler/api/templates/package.template.html

@@ -1,3 +1,46 @@
-<h2>{$ doc.name $}</h2>
+{% extends 'base.template.html' -%}
 
-A package
+{% macro listItems(items, title, overridePath) %}
+  {% set filteredItems = items | filterByPropertyValue('internal', undefined) %}
+  {% if filteredItems.length %}
+  <section class="export-list">
+    <h3>{$ title $}</h3>
+    <table class="is-full-width list-table">
+      {% for item in filteredItems %}
+      <tr>
+        <td><code><a href="{$ overridePath or item.path $}"{%- if item.deprecated != undefined %} class="deprecated-api-item"{% endif %}>{$ item.name $}</a></code></td>
+        <td>
+          {% if item.deprecated !== undefined %}{$ ('**Deprecated:** ' + item.deprecated) | marked $}{% endif %}
+          {% if item.shortDescription %}{$ item.shortDescription | marked $}{% endif %}
+        </td>
+      </tr>
+      {% endfor %}
+    </table>
+  </section>
+  {% endif %}
+{% endmacro %}
+
+{% block header %}
+<header class="api-header">
+  <h1>{$ doc.name $}</h1>
+  <label class="api-type-label {$ doc.docType $}">{$ doc.docType $}</label>
+  {% if doc.packageDeprecated or (not doc.isPrimaryPackage and doc.deprecated !== undefined) %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
+  {% if doc.security !== undefined %}<label class="api-status-label security">security</label>{% endif %}
+  {% if doc.pipeOptions.pure === 'false' %}<label class="api-status-label impure-pipe">impure</label>{% endif %}
+</header>
+{% endblock %}
+
+{% block body -%}
+  {$ doc.shortDescription | marked $}
+  {% if doc.description %}{$ doc.description | marked $}{% endif %}
+
+  {% include "includes/see-also.html" %}
+
+  <h2>{% if doc.isPrimaryPackage %}Primary entry{% else %}Entry{% endif %} point exports</h2>
+  {$ listItems(doc.modules, 'Modules') $}
+  {$ listItems(doc.classes, 'Classes') $}
+  {$ listItems(doc.decorators, 'Decorators') $}
+  {$ listItems(doc.functions, 'Functions') $}
+  {$ listItems(doc.structures, 'Structures') $}
+  {$ listItems(doc.types, 'Types') $}
+{%- endblock %}