Documentation Overhaul (#917)

* split docs package into `docs` and `docs-site`

`docs` is the documentalist theme.
`docs-site` is the blueprint-specific content for our docs site.
write reusable tag renderers for the common tags.
this is by no means finished, just a good place to start committing

* move BaseExample into `docs` package

* move typings around

* fix docs-site webpack compile errors!

* fix sass compile errors

* require react ^15.3 so we can use PureComponent
instead of pure-render-decorator

* clean up docs common files

- move ClickToCopy to docs-site cuz it's not used in docs
- rename to propsStore.ts
- delete unused PureComponent

* move FocusStyleManager call into Styleguide componentDidMount

so consumer doesn't have to set it.
also fix typings of setHotkeysDialogProps with Partial<>.

* fix html paths

* fix broken import (forgot to save)

* rename Styleguide to Documentation

* copyright headers

* move docs-site files into same structure as docs

components / styles / tags.
tags export maps of files for reactDocs and reactExample

* Documentation navbarLeft/Right props

BlueprintDocs component wraps Documentation with added themeName state. all theme logic moves to `docs-site` custom code.

* make some Documentation props optional

* remove theme from docs

* enable strictNullChecks in docs and docs-site!!

* move docs md file, rename styleguide.md to blueprint.md

* Update to documentalist 0.0.7

* move .d.ts and README around

* move normalize.css import to docs-site.scss

until we include it in blueprint.css itself!

* fix some small build errors

* add project files

* update links to docs-site

* Add top comment block to interface table tag renderer

* export BaseExample from docs package, refactor example imports

* fix CONTRIBUTING docs path

* Null check when naving to section

* Lint

* Add docs-site artifact

* Fix gulp watch task

* minor polish

CONTRIBUTING.md

@@ -29,7 +29,7 @@ A typical contributor workflow looks like this:
 1. Create a new feature branch. We use a format like `[your-initials]/[short-name]`:
    `bd/refactor-buttons`.
 1. Run the development server via `gulp` (no arguments).
-    - Navigate to http://localhost:9000/packages/docs/dist/ when the server starts.
+    - Navigate to http://localhost:9000/packages/docs-site/dist/ when the server starts.
     - See [Build tasks](https://github.com/palantir/blueprint/wiki/Build-tasks) on the wiki for more
       details on the inner workings of the Gulp build.
     - If you are contributing to the `table` or `landing` packages then run `npm start` in those

Gulpfile.js

@@ -71,11 +71,18 @@ const projects = [
     }, {
         id: "docs",
         cwd: "packages/docs/",
+        dependencies: ["core"],
+        sass: "compile",
+        typescript: true,
+    }, {
+        id: "docs-site",
+        cwd: "packages/docs-site/",
         dependencies: [
             // You must add your package to this dependency list if you have any
             // examples in the docs.
             "core",
             "datetime",
+            "docs",
             "table",
         ],
         sass: "bundle",
@@ -87,6 +94,7 @@ const projects = [
                 // (they all import @blueprint/* but don't actually have themselves in their node_modules)
                 "@blueprintjs/core",
                 "@blueprintjs/datetime",
+                "@blueprintjs/docs",
                 "@blueprintjs/table",
                 "dom4",
                 "moment",

README.md

@@ -38,7 +38,7 @@ __Prerequisite__: Node.js v6 or v7
 1. `npm install` to install build dependencies
 1. `npm run bootstrap` to install and link each package using [Lerna](https://lernajs.io/)
 1. `npm run gulp` to compile and start the server and watcher
-1. Open your browser to [localhost:9000/packages/docs/dist/](http://localhost:9000/packages/docs/dist/)
+1. Open your browser to [localhost:9000/packages/docs-site/dist/](http://localhost:9000/packages/docs-site/dist/)
 
 ## Contributing
 

circle.yml

@@ -4,6 +4,7 @@ general:
     - packages/core/dist
     - packages/datetime/dist
     - packages/docs/dist
+    - packages/docs-site/dist
     - packages/landing/dist
     - packages/table/dist
     # code coverage reports
@@ -22,6 +23,7 @@ dependencies:
     - packages/core/node_modules
     - packages/datetime/node_modules
     - packages/docs/node_modules
+    - packages/docs-site/node_modules
     - packages/landing/node_modules
     - packages/table/node_modules
   # non-zero exit codes in `dependencies` group will fail the build early

gulp/docs.js

@@ -10,7 +10,7 @@ module.exports = (blueprint, gulp, plugins) => {
     const text = require("./util/text");
     const spawn = require("child_process").spawn;
     const semver = require("semver");
-    const cwd = blueprint.findProject("docs").cwd;
+    const cwd = blueprint.findProject("docs-site").cwd;
 
     const config = {
         data: path.join(cwd, "src", "generated"),

gulp/watch.js

@@ -24,7 +24,7 @@ module.exports = (blueprint, gulp, plugins) => {
     gulp.task("watch-files", ["connect"], () => {
         blueprint.projectsWithBlock("sass").forEach((project) => {
             const tasks = [`sass-${project.id}:only`];
-            if (project.id !== "docs") {
+            if (project.id === "core") {
                 tasks.push("sass-variables");
             }
             gulp.watch(createSrcGlob(project, "*.scss"), tasks);
@@ -36,8 +36,8 @@ module.exports = (blueprint, gulp, plugins) => {
 
         gulp.watch("packages/*/!(node_modules)/**/*.md", ["docs-json"]);
 
-        // recompile docs CSS when non-docs dist/*.css files change
-        gulp.watch("packages/!(docs)/dist/*.css", ["sass-docs:only"]);
+        // recompile docs CSS when non-docs-site dist/*.css files change
+        gulp.watch("packages/!(docs-site)/dist/*.css", ["sass-docs-site:only"]);
     });
 
     gulp.task("watch", ["watch-files", "webpack-docs-watch"]);

gulp/webpack.js

@@ -7,7 +7,7 @@ module.exports = (blueprint, gulp) => {
     const webpack = require("webpack");
     const webpackConfig = require("./util/webpack-config");
 
-    const docsProject = blueprint.findProject("docs");
+    const docsProject = blueprint.findProject("docs-site");
     const configuration = webpackConfig.generateWebpackTypescriptConfig(docsProject);
 
     gulp.task("webpack-docs", ["docs"], (callback) => {

packages/core/examples/alertExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Alert, Button, Intent, IToaster, Toaster } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface IAlertExampleState {
     isOpen?: boolean;

packages/core/examples/buttonsExample.tsx

@@ -9,7 +9,7 @@ import * as classNames from "classnames";
 import * as React from "react";
 
 import { AnchorButton, Button, Classes, Intent, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface IButtonsExampleState {

packages/core/examples/collapseExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Button, Collapse } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class CollapseExample extends BaseExample<{ isOpen: boolean }> {
     public state = {

packages/core/examples/collapsibleListExample.tsx

@@ -17,7 +17,7 @@ import {
     RadioGroup,
     Slider,
 } from "@blueprintjs/core";
-import BaseExample, { handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleNumberChange } from "@blueprintjs/docs";
 
 export interface ICollapsibleListExampleState {
     collapseFrom?: CollapseFrom;

packages/core/examples/contextMenuExample.tsx

@@ -12,7 +12,7 @@ import * as PureRender from "pure-render-decorator";
 import * as React from "react";
 
 import { ContextMenu, ContextMenuTarget, Menu, MenuDivider, MenuItem } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 /**
  * This component uses the imperative ContextMenu API.

packages/core/examples/controlsExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Checkbox, Classes, Radio, RadioGroup, Switch } from "@blueprintjs/core";
-import BaseExample, { handleStringChange } from "./common/baseExample";
+import { BaseExample, handleStringChange } from "@blueprintjs/docs";
 
 export interface IControlsExampleState {
     radioValue?: string;

packages/core/examples/dropdownMenuExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Menu, MenuDivider, MenuItem, Popover, Position } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class DropdownMenuExample extends BaseExample<{}> {
     protected renderExample() {

packages/core/examples/editableTextExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, EditableText, Intent, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange, handleStringChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange, handleStringChange } from "@blueprintjs/docs";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface IEditableTextExampleState {

packages/core/examples/focusExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Button, FocusStyleManager, InputGroup, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 export interface IFocusExampleState {
     isFocusActive?: boolean;

packages/core/examples/hotkeyPiano.tsx

@@ -11,7 +11,7 @@ import * as classNames from "classnames";
 import * as React from "react";
 
 import { Hotkey, Hotkeys, HotkeysTarget } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 class Oscillator {
     public oscillator: OscillatorNode;

packages/core/examples/hotkeyTester.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { getKeyComboString, KeyCombo } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface IHotkeyTesterState {
     combo: string;

packages/core/examples/index.ts

@@ -5,8 +5,6 @@
  * and https://github.com/palantir/blueprint/blob/master/PATENTS
  */
 
-export * from "./common/baseExample";
-
 export * from "./alertExample";
 export * from "./buttonsExample";
 export * from "./collapseExample";

packages/core/examples/inputGroupExample.tsx

@@ -22,7 +22,7 @@ import {
     Tag,
     Tooltip,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleStringChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleStringChange } from "@blueprintjs/docs";
 
 export interface IInputGroupExampleState {
     disabled?: boolean;

packages/core/examples/menuExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, Menu, MenuDivider, MenuItem } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class MenuExample extends BaseExample<{}> {
     protected renderExample() {

packages/core/examples/nonIdealStateExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { InputGroup, NonIdealState } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class NonIdealStateExample extends BaseExample<{}> {
     protected renderExample() {

packages/core/examples/numericInputBasicExample.tsx

@@ -13,8 +13,8 @@ import {
     Position,
     Switch,
 } from "@blueprintjs/core";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface INumericInputBasicExampleState {

packages/core/examples/numericInputExtendedExample.tsx

@@ -9,8 +9,7 @@ import {
     Keys,
     NumericInput,
 } from "@blueprintjs/core";
-
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface INumericInputExtendedExampleState {
     value?: string;

packages/core/examples/overlayExample.tsx

@@ -17,7 +17,7 @@ import {
     Overlay,
     Switch,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 const OVERLAY_EXAMPLE_CLASS = "docs-overlay-example-transition";
 

packages/core/examples/popoverExample.tsx

@@ -21,7 +21,7 @@ import {
     Slider,
     Switch,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 
 const INTERACTION_KINDS = [
     { label: "Click", value: PopoverInteractionKind.CLICK.toString() },

packages/core/examples/progressExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Intent, ProgressBar, Slider, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface IProgressExampleState {

packages/core/examples/rangeSliderExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { NumberRange, RangeSlider } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface IRangeSliderExampleState {
     range?: NumberRange;

packages/core/examples/sliderExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Slider } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface ISliderExampleState {
     value1?: number;

packages/core/examples/spinnerExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, Spinner } from "@blueprintjs/core";
-import { handleStringChange } from "./common/baseExample";
+import { handleStringChange } from "@blueprintjs/docs";
 import { ProgressExample } from "./progressExample";
 
 const SIZES = [

packages/core/examples/tabs2Example.tsx

@@ -9,7 +9,7 @@ import * as classNames from "classnames";
 import * as React from "react";
 
 import { Classes, Switch, Tab2, Tabs2 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 export interface ITabs2ExampleState {
     activeTabId?: string;

packages/core/examples/tabsExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Switch, Tab, TabList, TabPanel, Tabs } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 export class TabsExample extends BaseExample<{ isVertical?: boolean }> {
     public state = {

packages/core/examples/tagExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, Intent, Tag } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class TagExample extends BaseExample<{ showTag?: boolean }> {
     public state = {

packages/core/examples/textExample.tsx

@@ -8,10 +8,9 @@
 import * as classNames from "classnames";
 import * as React from "react";
 
+import { BaseExample, handleStringChange } from "@blueprintjs/docs";
 import * as Classes from "../src/common/classes";
 import { Text } from "../src/components/text/text";
-import BaseExample from "./common/baseExample";
-import { handleStringChange } from "./common/baseExample";
 
 export interface ITextExampleState {
     textContent: string;

packages/core/examples/toastExample.tsx

@@ -19,7 +19,7 @@ import {
     Switch,
     Toaster,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 
 type IToastDemo = IToastProps & { button: string };
 

packages/core/examples/tooltipExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Intent, Popover, Position, Switch, Tooltip } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class TooltipExample extends BaseExample<{ isOpen: boolean }> {
     public state = {

packages/core/examples/treeExample.tsx

@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, ITreeNode, Tooltip, Tree } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface ITreeExampleState {
     nodes: ITreeNode[];

packages/core/examples/tsconfig.json

@@ -17,7 +17,8 @@
         "stripInternal": true,
         "target": "es5",
         "paths": {
-            "@blueprintjs/core": ["../dist/index"]
+            "@blueprintjs/core": ["../dist/index"],
+            "@blueprintjs/docs": ["../../docs/dist/index"]
         }
     }
 }

packages/core/src/components/hotkeys/hotkeysDialog.tsx

@@ -126,7 +126,7 @@ export function isHotkeysDialogShowing() {
     return HOTKEYS_DIALOG.isShowing();
 }
 
-export function setHotkeysDialogProps(props: IHotkeysDialogProps) {
+export function setHotkeysDialogProps(props: Partial<IHotkeysDialogProps>) {
     for (const key in props) {
         if (props.hasOwnProperty(key)) {
             (HOTKEYS_DIALOG.componentProps as any)[key] = (props as any)[key];