From 9f7479711e64eaedbd23466f946df262f67a5097 Mon Sep 17 00:00:00 2001
From: Fabio Berger <me@fabioberger.com>
Date: Sun, 29 Jul 2018 22:29:56 +0200
Subject: Improve doc gen script

---
 .../src/doc_generate_and_upload.ts                 | 32 ++++++++++++----------
 1 file changed, 17 insertions(+), 15 deletions(-)

(limited to 'packages')

diff --git a/packages/monorepo-scripts/src/doc_generate_and_upload.ts b/packages/monorepo-scripts/src/doc_generate_and_upload.ts
index b6a4801e3..592c36ae2 100644
--- a/packages/monorepo-scripts/src/doc_generate_and_upload.ts
+++ b/packages/monorepo-scripts/src/doc_generate_and_upload.ts
@@ -19,7 +19,7 @@ const args = yargs
         demandOption: true,
     })
     .option('isStaging', {
-        describe: 'Whether we with to publish docs to staging or production',
+        describe: 'Whether we wish to publish docs to staging or production',
         type: 'boolean',
         demandOption: true,
     })
@@ -65,23 +65,27 @@ export async function generateAndUploadDocsAsync(packageName: string, isStaging:
     // and see which specific files we must pass to TypeDoc.
     let typeDocExtraFileIncludes: string[] = [];
     _.each(exportPathToExportedItems, (exportedItems, exportPath) => {
+        const pathIfExists = pkgNameToPath[exportPath];
+        if (_.isUndefined(pathIfExists)) {
+            return; // It's an external package
+        }
+
         const isInternalToPkg = _.startsWith(exportPath, '.');
         if (isInternalToPkg) {
             const pathToInternalPkg = path.join(pathToPackage, 'src', `${exportPath}.ts`);
             typeDocExtraFileIncludes.push(pathToInternalPkg);
         }
-        const pathIfExists = pkgNameToPath[exportPath];
-        if (_.isUndefined(pathIfExists)) {
-            return; // It's an external package
-        }
         const typeDocSourceIncludes = new Set();
         const pathToIndex = `${pathIfExists}/src/index.ts`;
         const innerExportPathToExportedItems = getExportPathToExportedItems(pathToIndex);
         _.each(exportedItems, exportName => {
             _.each(innerExportPathToExportedItems, (innerExportItems, innerExportPath) => {
                 if (!_.startsWith(innerExportPath, './')) {
-                    // noop. Not an internal export... but rather an external one. Should we follow it?
-                    return;
+                    throw new Error(
+                        `GENERATE_UPLOAD_DOCS: WARNING - ${packageName} is exporting on of ${exportedItems} which is 
+                        itself exported from an external package. To fix this, export the external dependency directly, 
+                        not indirectly through ${exportPath}.`,
+                    );
                 }
                 if (_.includes(innerExportItems, exportName)) {
                     const absoluteSrcPath = path.join(pathIfExists, 'src', `${innerExportPath}.ts`);
@@ -90,21 +94,20 @@ export async function generateAndUploadDocsAsync(packageName: string, isStaging:
             });
         });
         // @0xproject/types & ethereum-types are examples of packages where their index.ts exports types
-        // directly, meaning no internal paths will exist to follow. This, we add the index file.
-        // TODO: Maybe we should add the index for all packages?
-        if (typeDocSourceIncludes.size === 0) {
-            typeDocSourceIncludes.add(pathToIndex);
-        }
+        // directly, meaning no internal paths will exist to follow. Other packages also have direct exports
+        // in their index.ts, so we always add it to the source files passed to TypeDoc
+        typeDocSourceIncludes.add(pathToIndex);
+
         typeDocExtraFileIncludes = [...typeDocExtraFileIncludes, ...Array.from(typeDocSourceIncludes)];
     });
 
     // Generate Typedoc JSON file
     const jsonFilePath = path.join(pathToPackage, 'generated_docs', 'index.json');
     const projectFiles = typeDocExtraFileIncludes.join(' ');
-    const cwd = path.join(constants.monorepoRootPath, 'packages/0x.js/');
+    const cwd = path.join(constants.monorepoRootPath, 'packages', packageName);
     // HACK: For some reason calling `typedoc` command directly from here, even with `cwd` set to the
     // packages root dir, does not work. It only works when called via a `package.json` script located
-    // in the packages root.
+    // in the package's root.
     await execAsync(`JSON_FILE_PATH=${jsonFilePath} PROJECT_FILES="${projectFiles}" yarn docs:json`, {
         cwd,
     });
@@ -115,7 +118,6 @@ export async function generateAndUploadDocsAsync(packageName: string, isStaging:
     const finalTypeDocOutput = _.clone(typedocOutput);
     _.each(typedocOutput.children, (file, i) => {
         const exportItems = findExportItemsGivenTypedocName(exportPathToExportedItems, packageName, file.name);
-        // Map file "name" to exportPath... HOW?!
         _.each(file.children, (child, j) => {
             if (!_.includes(exportItems, child.name)) {
                 delete finalTypeDocOutput.children[i].children[j];
-- 
cgit v1.2.3