[DM] Documentalist! #756

giladgray · 2017-03-02T01:12:17Z

targeting feature/documentalist branch

This is the big one!

replace KSS with Documentalist
replace both docs-interfaces and docs-kss gulp tasks with docs-json
refactor docs app to use DM: on its way to being a sweet React theme
- write a bunch of tag handlers
- delete Section component entirely, replaced with minimal Page SFC
- ~~🔥 remove [/] keybindings till we figure out layout~~ restored
- best scrollspy implementation yet! it's smooth as silk and never glitches out (only known issue is short final sections are hard to highlight)
generate layout tree (for nav) in gulp task
- requires some nasty rewriting of references 😢
- but hey it works really well!

NOTE: This PR should fix the build since that's kind of the point here.

⚠️ Expect hoards of design & content issues. Please list them here instead of commenting below:

navigator
scroll spy is missing
reloading on heading anchor (not page) loses place (ex: #components.card.interactive-cards)
search => typeahead => select doesn't properly link to destination page (duplicate of above anchor issue)
[ + ] key bindings

future PRs:

lingering .kss- class names
all CSS markup examples are missing
many React examples have borked styles
docs for other packages (only includes core here)

giladgray · 2017-03-02T01:58:40Z

oops! it seems the documentalist NPM package is missing the cli script. waiting on palantir/documentalist#5 for the fix and a new release.

massive deletions in gulp task! already had a pre-configured marked renderer for our syntax highlighting 👌

- write a bunch of tag handlers - able to delete Section component entirely, replaced with minimal Page SFC. - NavMenu needs much work - remove [/] keybindings till we figure out layout

- pretty nasty nesting algorithm generates new references for nested pages - need to fix some duplicate keys

althoug it only navigates to pages, not headings (for now).

blueprint-bot · 2017-03-02T23:23:06Z

bring back Navigator althoug it only navigates to pages, not headings (for now).

Preview: docs | table
Coverage: core | datetime

this may be the smoothest scrollspy implementation yet, though it's a little magical. iterate through headings from bottom and return first that is within X pixels of top of viewport.

remove context, destructure more, _prevProps. Page takes `page` prop instead of unspreading.

heading (not page) anchors are now supported brilliantly. the heading always ends up right at the top where you expect it. Styleguide builds a map of all section references to parent page to support this behavior with rapid lookup.

blueprint-bot · 2017-03-03T03:09:10Z

watch md files in gulp

Preview: docs | table
Coverage: core | datetime

the old #href behavior works fine now that i've fixed hash navigation.

blueprint-bot · 2017-03-03T03:31:07Z

styleguide docs, defaultPageId prop, remove unused interface

Preview: docs | table
Coverage: core | datetime

blueprint-bot · 2017-03-03T04:02:29Z

eachLayoutNode util function simplifies iteration

Preview: docs | table
Coverage: core | datetime

themadcreator

I think the only thing I'm not comfortable with is the removal of the hotkey navigation

themadcreator · 2017-03-03T19:52:15Z

packages/docs/src/index.tsx


 /* tslint:disable:no-var-requires */
-const pages = require<IStyleguideSection[]>("./generated/docs.json");
+const docs = require<IDocsData>("./generated/data.json");


docs.json seems like a more informative name that data.json

themadcreator · 2017-03-03T19:54:22Z

packages/docs/src/index.tsx

+    "###": renderHeading(3),
+    "####": renderHeading(4),
+    interface: resolveInterface,
+    page: () => undefined as JSX.Element,


what's this about? just to remove the @ tags?

every tag must have a handler, but pages don't get rendered in the flow.

i'd like to eventually render a cool link, kinda like the Resources page.

themadcreator · 2017-03-03T19:55:57Z

packages/docs/src/index.tsx

-// i think this is necessary because the negative margin trick doesn't work on page load
-// with react (might work via SSR where HTML is already there).
-// (80px = navbar height + content padding)
-scrollBy(0, -80);


themadcreator · 2017-03-03T19:56:49Z

packages/docs/src/components/styleguide.tsx

@@ -6,77 +6,59 @@
 */

 import * as classNames from "classnames";
+import { IPageData, IPageNode, isPageNode } from "documentalist/dist/client";


should we export these from the root of documentalist? don't we?

importing the root is not possible in a theme cuz it'll include postcss and typescript.
this is why the client file exists at all.

then maybe at least we should create a stub at the root instead so that we can import from "documentalist/client"

themadcreator · 2017-03-03T19:58:10Z

packages/docs/src/components/styleguide.tsx

-// initial page ID on load
-const DEFAULT_PAGE = "overview";
-
-@HotkeysTarget
 @PureRender


We'll want the hotkeys target back, won't we?

i removed the hotkeys here for now. we will want it back eventually.

I'm worried that we'll lose track of it an not add it back if we just delete in this 2-level-deep branch

So, i'll approve now, but please add an issue to track

see PR description TODO list

themadcreator · 2017-03-03T20:01:56Z

packages/docs/src/components/page.tsx

+            return renderer(node.value, i, page);
+        }
+    });
+    return <div>{pageContents}</div>;


worth adding a classname?

themadcreator · 2017-03-03T20:03:34Z

packages/docs/src/components/navigator.tsx

+        eachLayoutNode(this.props.items, (node, parents) => {
+            const { reference, title } = node;
+            const path = parents.map((p) => p.title).reverse();
+            const filterKey = [...path, title].join("/");


since path is already a new mutable array, i would have just done path.push(title)

nope, see the next line where path is used in the object and should not contain title.

ah, k. nothing to see here

themadcreator · 2017-03-03T20:04:52Z

packages/docs/src/components/navMenu.tsx

            </a>
            {props.children}
        </li>
    );
 };
+NavMenuItem.displayName = "Docs.NavMenuItem";


what's this for? debugging?

yes, it's a React thing. will be used in error messages

themadcreator · 2017-03-03T20:05:17Z

packages/docs/src/components/navMenu.tsx

@@ -9,56 +9,62 @@ import { Classes, IProps } from "@blueprintjs/core";
 import * as classNames from "classnames";
 import * as React from "react";

-import { IStyleguideSection } from "./styleguide";
+import { IHeadingNode, IPageNode, isPageNode } from "documentalist/dist/client";


we should really export these at the top level

doesn't matter, still can't import the root in this client because the root imports the plugins which import postcss and typescript which we do not want to include in the webpack bundle.

themadcreator · 2017-03-03T20:07:34Z

packages/docs/src/common/resolveDocs.ts

    if (docsComponent == null) {
-        throw new Error(`Unknown docs component: ${componentName}`);
+        console.error(`Unknown @reactDocs component: ${componentName}`);


console error instead of throwing? Should we switch other thrown errors like the not-found-example below?

then log and render error message. also give page a className.

giladgray · 2017-03-07T00:23:26Z

i've checked off everything for the TODO list in this PR so i'm gonna merge after the build. next steps are tracked in #796 so let's move the discussion over there. 🎆 📖 🎆

blueprint-bot · 2017-03-07T00:40:41Z

lint 😭

Preview: docs | landing | table
Coverage: core | datetime

* markdownify docs (#714) * convert all packages * script to convert scss docs to md files * remove Weights, convert to `@#+` * add pages for common files * add `@page` roots * 4-space md files (mostly for source) * remove some `parent` front matters * remove docs from .scss except markup & modifiers * [DM] forms docs nesting fixes (#755) * all files should start with `@#` depth is computed at layout time * split controls.md into three files so they all show up in nav * textarea gets its own file * add tsx syntax hints to code blocks * [DM] Documentalist! (#756) - 🎆 replace KSS with Documentalist - 🔨 replace both `docs-interfaces` and `docs-kss` gulp tasks with `docs-json` - ♻️ refactor docs app to use DM: on its way to being a sweet React theme - write a bunch of tag handlers - delete `Section` component entirely, replaced with minimal `Page` SFC - best scrollspy implementation yet! it's smooth as silk and never glitches out (only known issue is short final sections are hard to highlight) - 🌲 generate layout tree (for nav) in gulp task - requires some nasty rewriting of references 😢 - but hey it works really well! * fix duplicate typography.dark-theme key warning * Tabs2 docs in new page _really_ deprecate Tabs components * write components.md * nav only shows heading links when on that page * only scroll nav menu if active item is not visible * fix hotkey headings depth * 🐛 only scroll to heading when page changes otherwise scrolling up is damn near impossible! * delete KSS docs from common/ files already migrated to markdown in docs/ * restore Progress pages (bar/spinner/skeleton) decided simplest approach was a mostly empty root `progress` page that links to the other three. * fix slider duplicate key warning with new range-slider page decided not to create two child pages so Single Slider is on the root Sliders page. not sure about this pattern... * delete _tabs2.scss (docs only) and fix one code sample * [DM] KSS for CSS examples (#813) * update scss & md docs files - **scss files:** make them all valid KSS blocks again by adding header and reference. references are now reflective of the CSS class being documented. - **md files:** add `@css reference` tags in all the CSS API sections * documentalist@0.0.3 * css tag handler brings back markup & modifiers! * ♻️ major refactor to sections.scss a new function `reference()` to target these new KSS examples. refactored as many selectors as I could, and removed a bunch of obsolete ones. docs changes: * move checkbox "Inline controls" section * bring back button-group page, unwrap control-group markup * update typography docs for kss * [DM] docs for all packages (#818) * run all packages through Documentalist (easy glob change 👍) * index.md page for each package, _nav in docs * update nesting in datetime docs * title in styleguide * change default page * fix Table links, rename page to just Table * move color aliases table styles to live with its family * only update scroll position when page changes (#840) this solves the overscroll issue we had previously (cuz page doesn't change) while also ensuring that the active section is always visible when the page loads. sidebar scrolls the active _page_ into view so you can see the entire layout, rather than just the active section! * [DM] update documentalist for syntax highlighting (#846) & ensure handlebars grammar * [DM] React examples styles (#839) * add data-page-id to Page to give all Table examples a fixed height * BaseExample requires id prop, adds data-example-id attribute IBaseExample interface re-used in docs example renderer. BaseExample is the .kss-example, reducing element count by 1! * move .docs-overlay-example-transition styles all to _examples * sass example($name) function generates selector for react examples * InputGroupExample uses flex box utility classes * ContextMenuExample simpler render makes for simpler styles * remove now unused section-name() and section-id() functions * [DM] rename .kss-* → .docs-* (#850) * delete unused _markup.scss file * remove unused kss- things in html * wholesale rename .kss-* => .docs-* * [DM] squash some pages (#883) * merge the slider pages by omitting JavaScript API a daring play by ggray just lists the two components and takes advantage of documentalist's support for multiple tags per section! * move components usage instructions to styleguide they relate to all the packages so belong in a shared location, not inside Core Components. now the Core package is completely empty... * remove redundant UI icons heading in Icons as it was the only subheading. also refine the example a bit, using some handlebars! * [DM] core/components/button.javascript-api (#882) * nav layout code moves to MarkdownPlugin but must configure all plugins manually now * support IHeadingTag with single "heading" renderer TagRenderer receives ITag as first argument to support this polymorphism. use type in renderer definition to avoid redeclaring each argument. deconstruct and rename `value` as needed for minimal churn and maximal clarity. * refactor to support `route` property * IBlock field rename * documentalist@0.0.5 * [DM] nav nesting (#899) * documentalist@0.0.6: now with options use .d.ts files for typescript info, like we used to (shaves about 2s off runtime) * nav only expands active route, not all pages * 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 * [DM] update docs files and links (#927) * markdownify Text and DateRangeInput docs * fix all the links i could find * Fix text example tag * Fix text navbar issue * Fix tree example styles

Gilad Gray added 6 commits March 2, 2017 14:22

🎆 replace KSS with Documentalist

61dd695

massive deletions in gulp task! already had a pre-configured marked renderer for our syntax highlighting 👌

refactor docs styleguide to use DM

a0d74b3

- write a bunch of tag handlers - able to delete Section component entirely, replaced with minimal Page SFC. - NavMenu needs much work - remove [/] keybindings till we figure out layout

refactor resolvers to return JSX.Elements

12f1f11

generate layout tree in gulp task, fix NavMenu

20931c7

- pretty nasty nesting algorithm generates new references for nested pages - need to fix some duplicate keys

update references for heading nodes too in layout

4ce2170

remove docs-kss from watchers

c202ef4

giladgray force-pushed the gg/documentalist branch from 3ec631b to c202ef4 Compare March 2, 2017 22:30

Gilad Gray added 2 commits March 2, 2017 15:17

update documentalist version

9b66233

bring back Navigator

717039f

althoug it only navigates to pages, not headings (for now).

Gilad Gray added 4 commits March 2, 2017 18:48

🎆 restore scrollspy

6290a11

this may be the smoothest scrollspy implementation yet, though it's a little magical. iterate through headings from bottom and return first that is within X pixels of top of viewport.

react style refactors

86f674c

remove context, destructure more, _prevProps. Page takes `page` prop instead of unspreading.

🚀 heading anchor support!

869615c

heading (not page) anchors are now supported brilliantly. the heading always ends up right at the top where you expect it. Styleguide builds a map of all section references to parent page to support this behavior with rapid lookup.

watch md files in gulp

29d0ad2

Gilad Gray added 2 commits March 2, 2017 19:13

revert unnecessary NavigatorItem refactor

458af08

the old #href behavior works fine now that i've fixed hash navigation.

styleguide docs, defaultPageId prop, remove unused interface

f701f96

eachLayoutNode util function simplifies iteration

cd80fe5

themadcreator suggested changes Mar 3, 2017

View reviewed changes

themadcreator approved these changes Mar 3, 2017

View reviewed changes

Gilad Gray added 3 commits March 6, 2017 15:22

rename to docs.json + docs-json task

f217716

throw errors in tag renderers, catch them in page

fccb481

then log and render error message. also give page a className.

restore [ / ] hotkeys!

7eafda8

lint 😭

e7ec373

giladgray merged commit cce4dfe into feature/documentalist Mar 7, 2017

giladgray deleted the gg/documentalist branch March 7, 2017 01:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DM] Documentalist! #756

[DM] Documentalist! #756

giladgray commented Mar 2, 2017 •

edited

Loading

giladgray commented Mar 2, 2017

blueprint-bot commented Mar 2, 2017

blueprint-bot commented Mar 3, 2017

blueprint-bot commented Mar 3, 2017

blueprint-bot commented Mar 3, 2017

themadcreator left a comment

themadcreator Mar 3, 2017

themadcreator Mar 3, 2017

giladgray Mar 3, 2017

themadcreator Mar 3, 2017

themadcreator Mar 3, 2017

giladgray Mar 3, 2017 •

edited

Loading

themadcreator Mar 3, 2017

themadcreator Mar 3, 2017

giladgray Mar 3, 2017

themadcreator Mar 3, 2017

themadcreator Mar 3, 2017

giladgray Mar 3, 2017

themadcreator Mar 3, 2017

themadcreator Mar 3, 2017

giladgray Mar 3, 2017

themadcreator Mar 3, 2017

themadcreator Mar 3, 2017

giladgray Mar 3, 2017

themadcreator Mar 3, 2017

giladgray Mar 3, 2017 •

edited

Loading

themadcreator Mar 3, 2017

themadcreator Mar 3, 2017

giladgray commented Mar 7, 2017

blueprint-bot commented Mar 7, 2017

[DM] Documentalist! #756

[DM] Documentalist! #756

Conversation

giladgray commented Mar 2, 2017 • edited Loading

This is the big one!

giladgray commented Mar 2, 2017

blueprint-bot commented Mar 2, 2017

bring back Navigator althoug it only navigates to pages, not headings (for now).

blueprint-bot commented Mar 3, 2017

watch md files in gulp

blueprint-bot commented Mar 3, 2017

styleguide docs, defaultPageId prop, remove unused interface

blueprint-bot commented Mar 3, 2017

eachLayoutNode util function simplifies iteration

themadcreator left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

giladgray Mar 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

giladgray Mar 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

giladgray commented Mar 7, 2017

blueprint-bot commented Mar 7, 2017

lint 😭

giladgray commented Mar 2, 2017 •

edited

Loading

giladgray Mar 3, 2017 •

edited

Loading

giladgray Mar 3, 2017 •

edited

Loading