improve typescript documentation: enums & aliases!

README.md

@@ -100,7 +100,7 @@ Each library has its own dev script which you can run to watch changes to that p
 
 Much of Blueprint's documentation lives inside source code as JSDoc comments in `.tsx` files and KSS markup in `.scss` files. This documentation is extracted and converted into static JSON data using [documentalist](https://github.com/palantir/documentalist/).
 
-If you are updating documentation sources (_not_ the docs UI code which lives in `packages/docs-app` or the docs theme in `packages/docs-theme`), you'll need to run `yarn compile` from `packages/docs-data` to see changes reflected in the application.
+If you are updating documentation sources (_not_ the docs UI code which lives in `packages/docs-app` or the docs theme in `packages/docs-theme`), you'll need to run `yarn compile` from `packages/docs-data` to see changes reflected in the application. For simplicity, an alias script `yarn docs-data` exists in the root to minimize directory hopping.
 
 ### Updating icons
 

package.json

@@ -16,7 +16,7 @@
     "deploy": "gh-pages -d docs -b master",
     "dev:all": "lerna run dev --parallel --scope '!@blueprintjs/{landing-app,table-dev-app}'",
     "dev:core": "lerna run dev --parallel --scope '@blueprintjs/{core,docs-app}'",
-    "dev:docs": "lerna run dev --parallel --scope '@blueprintjs/{docs,docs-app}'",
+    "dev:docs": "lerna run dev --parallel --scope '@blueprintjs/{docs-app,docs-theme}'",
     "dev:datetime": "lerna run dev --parallel --scope '@blueprintjs/{core,datetime,docs-app}'",
     "dev:labs": "lerna run dev --parallel --scope '@blueprintjs/{core,labs,select,docs-app}'",
     "dev:landing": "lerna run dev --parallel --scope '@blueprintjs/{core,landing-app}'",
@@ -26,6 +26,7 @@
     "dist:libs": "lerna run dist --parallel --scope '@blueprintjs/{core,datetime,docs-theme,icons,labs,select,table,timezone}'",
     "dist:apps": "lerna run dist --parallel --scope '@blueprintjs/{docs-app,landing-app,table-dev-app}'",
     "dist:docs": "run-s clean-docs copy-docs-app copy-landing-app",
+    "docs-data": "lerna run compile --scope '@blueprintjs/docs-data'",
     "lint": "lerna run --parallel lint",
     "lint-fix": "lerna run --parallel lint-fix",
     "test": "lerna run --parallel test",

packages/docs-app/src/index.tsx

@@ -29,7 +29,7 @@ const reactDocs = new ReactDocsTagRenderer(ReactDocs as any);
 const reactExample = new ReactExampleTagRenderer(reactExamples);
 
 const tagRenderers = {
-    ...createDefaultRenderers(docs),
+    ...createDefaultRenderers(),
     reactDocs: reactDocs.render,
     reactExample: reactExample.render,
 };

packages/docs-data/compile-docs-data

@@ -55,10 +55,11 @@ function generateDocumentalistData() {
             new dm.TypescriptPlugin({
                 excludeNames: [/I.+State$/],
                 excludePaths: ["node_modules/", "-app/", "test-commons/"],
+                tsconfigPath: path.resolve(__dirname, "../../config/tsconfig.base.json"),
             }),
         )
         .use(".scss", new dm.KssPlugin())
-        .documentGlobs("../*/src/**/*.{ts,tsx,scss,md}")
+        .documentGlobs("../*/src/**/*.{scss,md}", "../*/src/index.{ts,tsx}")
         .then(docs => JSON.stringify(docs, transformDocumentalistData, 2))
         .then(content => fs.writeFileSync(path.join(GENERATED_SRC_DIR, DOCS_DATA_FILENAME), content));
 }

packages/docs-data/package.json

@@ -10,11 +10,12 @@
   },
   "dependencies": {
     "@blueprintjs/docs-theme": "^2.0.0-beta.1",
-    "documentalist": "^1.0.0-beta.1",
+    "documentalist": "^1.0.0-beta.4",
     "glob": "^7.1.2",
     "highlights": "^3.1.1",
     "marked": "^0.3.6",
-    "semver": "^5.4.1"
+    "semver": "^5.4.1",
+    "typescript": "2.4.1"
   },
   "repository": {
     "type": "git",

packages/docs-theme/package.json

@@ -26,7 +26,7 @@
   "dependencies": {
     "@blueprintjs/core": "^2.0.0-beta.1",
     "classnames": "^2.2",
-    "documentalist": "^1.0.0-beta.1",
+    "documentalist": "^1.0.0-beta.4",
     "fuzzaldrin-plus": "^0.5.0",
     "tslib": "^1.5.0"
   },

packages/docs-theme/src/common/context.ts

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2017 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the terms of the LICENSE file distributed with this project.
+ */
+
+import { Utils } from "@blueprintjs/core";
+import { IBlock, IKssPluginData, IMarkdownPluginData, ITypescriptPluginData } from "documentalist/dist/client";
+
+/** This docs theme requires Markdown data and optionally supports Typescript and KSS data. */
+export type IDocsData = IMarkdownPluginData & (ITypescriptPluginData | {}) & (IKssPluginData | {});
+
+export function hasTypescriptData(docs: IDocsData): docs is IMarkdownPluginData & ITypescriptPluginData {
+    return docs != null && (docs as ITypescriptPluginData).typescript != null;
+}
+
+export function hasKssData(docs: IDocsData): docs is IMarkdownPluginData & IKssPluginData {
+    return docs != null && (docs as IKssPluginData).css != null;
+}
+
+/**
+ * Use React context to transparently provide helpful functions to children.
+ * This is basically the pauper's Redux store connector: some central state from the root
+ * `Documentation` component is exposed to its children so those in the know can speak
+ * directly to their parent.
+ */
+export interface IDocumentationContext {
+    /**
+     * Get the Documentalist data.
+     * Use the `hasTypescriptData` and `hasKssData` typeguards before accessing those plugins' data.
+     */
+    getDocsData(): IDocsData;
+
+    /** Render a block of Documentalist documentation to a React node. */
+    renderBlock(block: IBlock): React.ReactNode;
+
+    /** Render a Documentalist Typescript type string to a React node. */
+    renderType(type: string): React.ReactNode;
+}
+
+/**
+ * To enable context access in a React component, assign `static contextTypes` and declare `context` type:
+ *
+ * ```tsx
+ * export class ContextComponent extends React.PureComponent<IApiLinkProps> {
+ *     public static contextTypes = DocumentationContextTypes;
+ *     public context: IDocumentationContext;
+ *
+ *     public render() {
+ *         return this.context.renderBlock(this.props.block);
+ *     }
+ * }
+ * ```
+ */
+export const DocumentationContextTypes: React.ValidationMap<IDocumentationContext> = {
+    getDocsData: assertFunctionProp,
+    renderBlock: assertFunctionProp,
+    renderType: assertFunctionProp,
+};
+
+// simple alternative to prop-types dependency
+function assertFunctionProp<T>(obj: T, key: keyof T) {
+    if (obj[key] != null && Utils.isFunction(obj[key])) {
+        return undefined;
+    }
+    return new Error(`[Blueprint] Documentation context ${key} must be function.`);
+}

packages/docs-theme/src/common/utils.ts

@@ -71,3 +71,16 @@ export function eachLayoutNode(
         }
     });
 }
+
+/**
+ * Minimal markdown renderer that supports only backtick `code` elements and triple-backtick `pre` elements.
+ * Does not provide any syntax highlighting.
+ */
+export function markdownCode(text: string) {
+    return {
+        __html: text
+            .replace("<", "&lt;")
+            .replace(/```([^`]+)```/g, (_, code) => `<pre>${code}</pre>`)
+            .replace(/`([^`]+)`/g, (_, code) => `<code>${code}</code>`),
+    };
+}

packages/docs-theme/src/components/block.tsx

@@ -4,12 +4,12 @@
  * Licensed under the terms of the LICENSE file distributed with this project.
  */
 
-import { IBlock, IPageData } from "documentalist/dist/client";
+import { IBlock } from "documentalist/dist/client";
 import * as React from "react";
 
-import { ITagRendererMap, TagElement } from "../tags";
+import { ITagRendererMap } from "../tags";
 
-export function renderBlock(block: IBlock | undefined, tagRenderers: ITagRendererMap, page?: IPageData): TagElement[] {
+export function renderBlock(block: IBlock | undefined, tagRenderers: ITagRendererMap): JSX.Element[] {
     if (block === undefined) {
         return [];
     }
@@ -22,11 +22,11 @@ export function renderBlock(block: IBlock | undefined, tagRenderers: ITagRendere
             if (renderer === undefined) {
                 throw new Error(`Unknown @tag: ${node.tag}`);
             }
-            return renderer(node, i, tagRenderers, page);
+            return React.createElement(renderer, { ...node, key: i });
         } catch (ex) {
             console.error(ex.message);
             return (
-                <h3>
+                <h3 key={`__error-${i}`}>
                     <code>{ex.message}</code>
                 </h3>
             );

packages/docs-theme/src/components/documentation.tsx

@@ -5,13 +5,15 @@
  */
 
 import * as classNames from "classnames";
-import { IMarkdownPluginData, isPageNode } from "documentalist/dist/client";
+import { isPageNode, linkify } from "documentalist/dist/client";
 import * as React from "react";
 
 import { FocusStyleManager, Hotkey, Hotkeys, HotkeysTarget, IProps, Utils } from "@blueprintjs/core";
 
+import { DocumentationContextTypes, hasTypescriptData, IDocsData, IDocumentationContext } from "../common/context";
 import { eachLayoutNode } from "../common/utils";
-import { TagRenderer } from "../tags";
+import { ITagRendererMap } from "../tags";
+import { renderBlock } from "./block";
 import { Navigator } from "./navigator";
 import { NavMenu } from "./navMenu";
 import { Page } from "./page";
@@ -24,9 +26,9 @@ export interface IDocumentationProps extends IProps {
 
     /**
      * All the docs data from Documentalist.
-     * Must include at least  `{ nav, pages }` from the MarkdownPlugin.
+     * This theme requires the Markdown plugin, and optionally supports Typescript and KSS data.
      */
-    docs: IMarkdownPluginData;
+    docs: IDocsData;
 
     /**
      * Callback invoked whenever the component props or state change (specifically,
@@ -36,7 +38,7 @@ export interface IDocumentationProps extends IProps {
     onComponentUpdate?: (pageId: string) => void;
 
     /** Tag renderer functions. Unknown tags will log console errors. */
-    tagRenderers: { [tag: string]: TagRenderer };
+    tagRenderers: ITagRendererMap;
 
     /**
      * Elements to render on the left side of the navbar, typically logo and title.
@@ -59,6 +61,8 @@ export interface IDocumentationState {
 
 @HotkeysTarget
 export class Documentation extends React.PureComponent<IDocumentationProps, IDocumentationState> {
+    public static childContextTypes = DocumentationContextTypes;
+
     public static defaultProps = {
         navbarLeft: "Documentation",
     };
@@ -88,6 +92,17 @@ export class Documentation extends React.PureComponent<IDocumentationProps, IDoc
         });
     }
 
+    public getChildContext(): IDocumentationContext {
+        const { docs } = this.props;
+        return {
+            getDocsData: () => docs,
+            renderBlock: block => renderBlock(block, this.props.tagRenderers),
+            renderType: hasTypescriptData(docs)
+                ? type => linkify(type, docs.typescript, name => <u key={name}>{name}</u>)
+                : type => type,
+        };
+    }
+
     public render() {
         const { activePageId, activeSectionId } = this.state;
         const { nav, pages } = this.props.docs;

packages/docs-theme/src/components/page.tsx

@@ -16,7 +16,7 @@ export interface IPageProps {
 }
 
 export const Page: React.SFC<IPageProps> = ({ tagRenderers, page }) => {
-    const pageContents = renderBlock(page, tagRenderers, page);
+    const pageContents = renderBlock(page, tagRenderers);
     return (
         <div className="docs-page" data-page-id={page.reference}>
             {pageContents}