generalize docs data (#63)

* restore props tables!
ensure docs tasks run after sources are compiled

* generalize releases and versions
they both accept an `IPackageInfo`, which now includes `url` field.
resolve the URLs at require time (means we can use regular links
for documentation versions).

* add resolveInterface prop
functions similarly to the other `resolve*` props.
we provide a `PropsStore` class that can intelligently resolve props
including inheritance.
this is necessary because the previous impl used a relative path
that does not exist in internal repo.

gulp/aliases.js

@@ -23,12 +23,12 @@ module.exports = (gulp) =>{
     gulp.task("docs", ["docs-interfaces", "docs-kss", "docs-versions", "docs-releases"]);
 
     // perform a full build of the code and then finish
-    gulp.task("build", (done) => rs("clean", ["compile", "docs"], "webpack-compile-docs", done));
+    gulp.task("build", (done) => rs("clean", "compile", "docs", "webpack-compile-docs", done));
 
     // build code, run unit tests, terminate
     // NOTE: `npm test` runs each of these tasks separately to free up memory between them
     gulp.task("test", (done) => rs("karma", "test-typescript-2.0", done));
 
     // compile code and start watching for development
-    gulp.task("default", (done) => rs("clean", ["compile", "docs"], "watch", done));
+    gulp.task("default", (done) => rs("clean", "compile", "docs", "watch", done));
 };

packages/docs/src/common/propsStore.tsx

@@ -0,0 +1,30 @@
+import { IInterfaceEntry, IPropertyEntry } from "ts-quick-docs/src/interfaces";
+
+export class PropsStore {
+    constructor(private props: IInterfaceEntry[]) {}
+
+    public getProps = (name: string): IPropertyEntry[] => {
+        const entry = this.props.filter((props) => props.name === name)[0];
+        if (entry == null) {
+            return [];
+        } else if (entry.extends == null) {
+            return entry.properties;
+        } else {
+            // dirty deduplication for overridden/inherited props
+            const props: {[name: string]: IPropertyEntry} = {};
+            entry.extends.map(this.getInheritedProps).forEach((inherited) => {
+                inherited.forEach((prop) => props[prop.name] = prop);
+            });
+            entry.properties.forEach((prop) => props[prop.name] = prop);
+            // return a sorted array of unique props
+            return Object.keys(props).sort().map((n) => props[n]);
+        }
+    }
+
+    private getInheritedProps = (name: string) => {
+        return this.getProps(name).map((p) => {
+            p.inheritedFrom = name;
+            return p;
+        });
+    }
+}

packages/docs/src/components/navbar.tsx

@@ -28,9 +28,6 @@ export interface INavbarProps {
     useDarkTheme: boolean;
 }
 
-/* tslint:disable-next-line:max-line-length */
-const NPM_URL_BASE = "https://www.npmjs.com/package";
-
 @PureRender
 @HotkeysTarget
 export class Navbar extends React.Component<INavbarProps, {}> {
@@ -79,7 +76,7 @@ export class Navbar extends React.Component<INavbarProps, {}> {
     private renderReleasesMenu() {
         const menuItems = this.props.releases.map((version: IPackageInfo, index: number) => (
             <MenuItem
-                href={`${NPM_URL_BASE}/${version.name}`}
+                href={version.url}
                 key={index}
                 label={version.version}
                 target="_blank"
@@ -105,16 +102,12 @@ export class Navbar extends React.Component<INavbarProps, {}> {
     }
 }
 
-function handleVersionChange(release: string) {
-    return () => location.href = `https://palantir.github.io/blueprint/${release}`;
-}
-
-export const NavbarLeft: React.SFC<{ versions: string[] }> = ({ versions }) => {
+export const NavbarLeft: React.SFC<{ versions: IPackageInfo[] }> = ({ versions }) => {
     const match = /releases\/([^\/]+)\/build/.exec(location.href);
     // default to latest release if we can't find a tag in the URL
-    const currentRelease = (match == null ? versions[0] : match[1]);
+    const currentRelease = (match == null ? versions[0].version : match[1]);
     const releaseItems = versions.map((rel, i) => (
-        <MenuItem key={i} onClick={handleVersionChange(rel)} text={rel} />
+        <MenuItem key={i} href={rel.url} text={rel.version} />
     ));
     const menu = <Menu className="docs-version-list">{releaseItems}</Menu>;
 
@@ -130,3 +123,4 @@ export const NavbarLeft: React.SFC<{ versions: string[] }> = ({ versions }) => {
         </div>
     );
 };
+NavbarLeft.displayName = "Docs.NavbarLeft";

packages/docs/src/components/section.tsx

@@ -9,7 +9,6 @@ import * as PureRender from "pure-render-decorator";
 import * as React from "react";
 import { IPropertyEntry } from "ts-quick-docs/src/interfaces";
 
-import { getProps } from "../common/props";
 import { ExampleComponentClass } from "../common/resolveExample";
 import { getTheme } from "../common/theme";
 import { ModifierTable } from "./modifierTable";
@@ -59,6 +58,7 @@ export class Section extends React.Component<ISectionProps, {}> {
                 key={s.reference}
                 resolveDocs={this.props.resolveDocs}
                 resolveExample={this.props.resolveExample}
+                resolveInterface={this.props.resolveInterface}
                 section={s}
             />
         ));
@@ -89,7 +89,7 @@ export class Section extends React.Component<ISectionProps, {}> {
 
     public componentWillMount() {
         // compute this once since it'll never change and is potentially expensive with inheritance
-        this.interfaceProps = getProps(this.props.section.interfaceName);
+        this.interfaceProps = this.props.resolveInterface(this.props.section.interfaceName);
     }
 
     private maybeRenderModifiers() {

packages/docs/src/components/styleguide.tsx

@@ -6,6 +6,7 @@
 import * as classNames from "classnames";
 import * as PureRender from "pure-render-decorator";
 import * as React from "react";
+import { IPropertyEntry } from "ts-quick-docs/src/interfaces";
 
 import { Hotkey, Hotkeys, HotkeysTarget, IHotkeysDialogProps, setHotkeysDialogProps } from "@blueprintjs/core";
 
@@ -16,6 +17,9 @@ import { Navigator } from "./navigator";
 import { NavMenu } from "./navMenu";
 import { Section } from "./section";
 
+// these interfaces are essential to the docs app, so it's helpful to re-export here
+export { IInterfaceEntry, IPropertyEntry } from "ts-quick-docs/src/interfaces";
+
 const DARK_THEME = "pt-dark";
 const LIGHT_THEME = "";
 
@@ -45,7 +49,9 @@ export interface IStyleguideSection {
 }
 
 export interface IPackageInfo {
-    name: string;
+    /** Name of package. Ignored for documentation site versions. */
+    name?: string;
+    url: string;
     version: string;
 }
 
@@ -55,6 +61,9 @@ export interface IStyleguideExtensionProps {
 
     /** Given a section, returns the example component that should be rendered for it. */
     resolveExample(section: IStyleguideSection): IResolvedExample;
+
+    /** Given an interface name, returns an array of properties defined on the interface. */
+    resolveInterface(name: string): IPropertyEntry[];
 }
 
 export interface IStyleguideProps extends IStyleguideExtensionProps {
@@ -68,7 +77,7 @@ export interface IStyleguideProps extends IStyleguideExtensionProps {
     pages: IStyleguideSection[];
 
     /** Release versions for published documentation. */
-    versions: string[];
+    versions: IPackageInfo[];
 
     /** Latest release versions for published projects. */
     releases: IPackageInfo[];
@@ -140,6 +149,7 @@ export class Styleguide extends React.Component<IStyleguideProps, IStyleguideSta
                         <Section
                             resolveDocs={this.props.resolveDocs}
                             resolveExample={this.props.resolveExample}
+                            resolveInterface={this.props.resolveInterface}
                             section={activePage}
                         />
                     </article>

packages/docs/src/index.tsx

@@ -8,15 +8,27 @@ import "dom4";
 import { FocusStyleManager } from "@blueprintjs/core";
 import * as React from "react";
 import * as ReactDOM from "react-dom";
+import { IInterfaceEntry } from "ts-quick-docs/src/interfaces";
 
+import { PropsStore } from "./common/propsStore";
 import { resolveDocs } from "./common/resolveDocs";
 import { resolveExample } from "./common/resolveExample";
 import { IPackageInfo, IStyleguideSection, Styleguide } from "./components/styleguide";
 
 /* tslint:disable:no-var-requires */
 const pages = require<IStyleguideSection[]>("./generated/docs.json");
-const releases = require<IPackageInfo[]>("./generated/releases.json");
-const versions = require<string[]>("./generated/versions.json").reverse();
+const releases = require<IPackageInfo[]>("./generated/releases.json")
+    .map((pkg) => {
+        pkg.url = `https://www.npmjs.com/package/${pkg.name}`;
+        return pkg;
+    });
+const versions = require<string[]>("./generated/versions.json").reverse()
+    .map((version) => ({
+        url: `https://palantir.github.io/blueprint/docs/${version}`,
+        version,
+    } as IPackageInfo));
+
+const propsStore = new PropsStore(require<IInterfaceEntry[]>("./generated/props.json"));
 /* tslint:enable:no-var-requires */
 
 // This function is called whenever the documentation page changes and should be used to
@@ -34,6 +46,7 @@ ReactDOM.render(
     <Styleguide
         resolveDocs={({ reactDocs }) => resolveDocs(reactDocs)}
         resolveExample={({ reactExample }) => resolveExample(reactExample)}
+        resolveInterface={propsStore.getProps}
         pages={pages}
         onUpdate={updateExamples}
         releases={releases}