Documentation Overhaul #917

themadcreator · 2017-03-30T22:06:00Z

We now intend to publish @blueprintjs/docs as its own package. It contains the <Documentation> React component that is built to consume and render Documentalist output.

The documentation has been restructured to use Documentalist to parse all typescript, sass, and markdown across all Blueprint packages then render using this new @blueprintjs/docs package.

The Blueprint-specific content (such as the logo, dark theme switcher, etc.) have been moved into packages/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

instead of pure-render-decorator

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

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

…into feature/publish-docs

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

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

…into feature/publish-docs

until we include it in blueprint.css itself!

…into feature/publish-docs

blueprint-bot · 2017-03-30T22:42:17Z

Add docs-site artifact

Preview: docs | table
Coverage: core | datetime

blueprint-bot · 2017-03-30T23:04:23Z

Fix gulp watch task

Preview: docs | table
Coverage: core | datetime

blueprint-bot · 2017-03-31T00:28:49Z

minor polish

Preview: documentation | table
Coverage: core | datetime

adidahiya · 2017-03-31T04:49:23Z

we lost date range input? 🤔

giladgray

@adidahiya i'll fix content (and oh some many links) in the next and final DM PR. we're also missing Text for the same reason: it merged after I started the feature branch.

giladgray · 2017-03-31T00:11:50Z

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>) {


note: this is a pretty critical change because IHotkeysDialogProps requires isOpen (since it extends IDialogProps) but that's not reasonable to pass here.

giladgray · 2017-03-31T00:21:06Z

packages/docs/tsconfig.json

@@ -1,44 +1,29 @@
 {


this is the same tsconfig that core & datetime etc use because docs is now a publish-able package.

cmslewis

LGTM, and I have nothing of substance to say. I also don't feel like a good person to approve this outright.

cmslewis · 2017-03-31T19:06:29Z

packages/docs-site/src/components/clickToCopy.tsx

@@ -60,7 +57,7 @@ export class ClickToCopy extends React.Component<IClickToCopyProps, IClickToCopy
        return (
            <div
                {...removeNonHTMLProps(this.props, ["copiedClassName", "value"], true)}
-                className={classNames("docs-clipboard", className, { [copiedClassName]: this.state.hasCopied })}
+                className={classNames("docs-clipboard", className, { [copiedClassName!]: this.state.hasCopied })}


whaaaaaat does this syntax mean

strictNullChecks assert that something is defined (remove | undefined basically). necessary because most props are marked optional so they're not required in the JSX.

ah, so a TS thing. cool, TIL.

cmslewis · 2017-03-31T19:07:11Z

packages/docs-site/src/components/clickToCopy.tsx

@@ -38,8 +36,7 @@ export interface IClickToCopyState {
 *  - `[data-copied-message="<message>"]` will be shown when the element has been copied.
 * The message is reset to default when the user mouses off the element after copying it.
 */
-@PureRender
-export class ClickToCopy extends React.Component<IClickToCopyProps, IClickToCopyState> {
+export class ClickToCopy extends React.PureComponent<IClickToCopyProps, IClickToCopyState> {


does this need to happen in this PR?

this package is private so it doesn't matter what we do inside. there is no harm in this.

just seemed like making this change now would bloat the number of files affected in this PR unnecessarily. but yeah, no harm in it.

cmslewis · 2017-03-31T19:08:53Z

packages/docs-site/src/components/colorSchemes.tsx

@@ -68,8 +65,7 @@ export interface IColorSchemeState {
    steps?: number;
 }

-@PureRender
-export class ColorScheme extends React.Component<IColorSchemeProps, IColorSchemeState> {
+export class ColorScheme extends React.PureComponent<IColorSchemeProps, IColorSchemeState> {


oh boy here we go

where are we going? this package is private. no one will be the wiser.

* 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 and others added 30 commits March 28, 2017 17:24

split docs package into docs and docs-site

a56b804

`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

f0f781f

move typings around

62ec82e

fix docs-site webpack compile errors!

167eb96

fix sass compile errors

57d6798

require react ^15.3 so we can use PureComponent

6fea121

instead of pure-render-decorator

clean up docs common files

a817270

- 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

e87dea5

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

fix html paths

023b159

fix broken import (forgot to save)

fa7373f

rename Styleguide to Documentation

1ae362d

copyright headers

f29d78e

Merge branch 'feature/publish-docs' of github.com:palantir/blueprint …

92cc546

…into feature/publish-docs

move docs-site files into same structure as docs

1d4dfa5

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

Documentation navbarLeft/Right props

2681625

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

make some Documentation props optional

cb396ab

remove theme from docs

2b45ad3

enable strictNullChecks in docs and docs-site!!

27195bf

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

bbc98bb

Update to documentalist 0.0.7

44a4349

Merge branch 'feature/publish-docs' of github.com:palantir/blueprint …

8850502

…into feature/publish-docs

move .d.ts and README around

601d1b8

move normalize.css import to docs-site.scss

591ab86

until we include it in blueprint.css itself!

fix some small build errors

01a3687

add project files

73d8def

update links to docs-site

88d3697

Add top comment block to interface table tag renderer

19e3661

Merge branch 'feature/publish-docs' of github.com:palantir/blueprint …

536877e

…into feature/publish-docs

export BaseExample from docs package, refactor example imports

56f4a34

fix CONTRIBUTING docs path

ec3be13

Null check when naving to section

f1d3d69

themadcreator changed the base branch from master to feature/documentalist March 30, 2017 22:06

themadcreator added 2 commits March 30, 2017 15:27

Lint

05081e1

Add docs-site artifact

10c9a69

Fix gulp watch task

7c01073

themadcreator requested review from cmslewis and giladgray March 30, 2017 23:25

minor polish

d4eb32b

giladgray reviewed Mar 31, 2017

View reviewed changes

cmslewis reviewed Mar 31, 2017

View reviewed changes

giladgray merged commit 3290f79 into feature/documentalist Mar 31, 2017

giladgray deleted the feature/publish-docs branch March 31, 2017 19:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation Overhaul #917

Documentation Overhaul #917

themadcreator commented Mar 30, 2017

blueprint-bot commented Mar 30, 2017

blueprint-bot commented Mar 30, 2017

blueprint-bot commented Mar 31, 2017

adidahiya commented Mar 31, 2017

giladgray left a comment •

edited

Loading

giladgray Mar 31, 2017

giladgray Mar 31, 2017

cmslewis left a comment

cmslewis Mar 31, 2017

giladgray Mar 31, 2017

cmslewis Mar 31, 2017

cmslewis Mar 31, 2017

giladgray Mar 31, 2017

cmslewis Mar 31, 2017

cmslewis Mar 31, 2017

giladgray Mar 31, 2017

Documentation Overhaul #917

Documentation Overhaul #917

Conversation

themadcreator commented Mar 30, 2017

blueprint-bot commented Mar 30, 2017

Add docs-site artifact

blueprint-bot commented Mar 30, 2017

Fix gulp watch task

blueprint-bot commented Mar 31, 2017

minor polish

adidahiya commented Mar 31, 2017

giladgray left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cmslewis 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

giladgray left a comment •

edited

Loading