aboutsummaryrefslogtreecommitdiffstats
path: root/packages
diff options
context:
space:
mode:
authorFabio Berger <me@fabioberger.com>2018-07-30 04:29:56 +0800
committerFabio Berger <me@fabioberger.com>2018-07-30 04:29:56 +0800
commit9f7479711e64eaedbd23466f946df262f67a5097 (patch)
tree13df34633ac1f87d56b47cebabcaeb1f914150dd /packages
parent4579e1637d9f4d0d7badb23336af6785330c6ecc (diff)
downloaddexon-sol-tools-9f7479711e64eaedbd23466f946df262f67a5097.tar
dexon-sol-tools-9f7479711e64eaedbd23466f946df262f67a5097.tar.gz
dexon-sol-tools-9f7479711e64eaedbd23466f946df262f67a5097.tar.bz2
dexon-sol-tools-9f7479711e64eaedbd23466f946df262f67a5097.tar.lz
dexon-sol-tools-9f7479711e64eaedbd23466f946df262f67a5097.tar.xz
dexon-sol-tools-9f7479711e64eaedbd23466f946df262f67a5097.tar.zst
dexon-sol-tools-9f7479711e64eaedbd23466f946df262f67a5097.zip
Improve doc gen script
Diffstat (limited to 'packages')
-rw-r--r--packages/monorepo-scripts/src/doc_generate_and_upload.ts32
1 files changed, 17 insertions, 15 deletions
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];