improve typescript documentation: enums & aliases! #1982

giladgray · 2018-01-09T22:34:29Z

Changes proposed in this pull request:

There's a lot going on here, sorry! I had a good time over break hacking on the docs renderers.

tag renderers are now just React.SFC<ITag>, none of that awkward class with a render method.
- except for @reactExample and @reactDocs, which still use a class cuz their data comes from outside documentalist
add context to Documentation root component which exposes renderBlock, renderType, and getDocsData functions, rather than passing huge data blobs around through props.
⭐️ @interface tag now supports enums and type aliases too!!! (this is not demonstrated in the docs yet...)
- greatly improved header includes kind, inheritance info, and link to source with package name!
Documentation requires Markdown data, optionally accepts Typescript and KSS data.

Reviewers should focus on:

the typescript data now includes non-interface-y things (namely enums and type aliases). should we rename the @interface tag to @typescript to match @css?

remove page arg from renderBlock

…ata to children

…ring

blueprint-bot · 2018-01-09T23:18:48Z

createDefaultRenderers()

Preview: documentation

giladgray · 2018-01-10T00:59:19Z

well fudge, we've got a big problem:

extends any, and it's missing all the extended props.
i've been trying to chase this down for like an hour and made no progress. it works perfectly when debugging in VSCode against actual blueprint source, but fails when run from blueprint itself.

giladgray · 2018-01-10T01:23:49Z

ok i figured it out! must set tsconfig path so it knows how to compile our code. palantir/documentalist#58

blueprint-bot · 2018-01-10T01:46:34Z

tsconfigPath option fixes interface inheritance!!!

Preview: documentation

giladgray · 2018-01-10T01:51:12Z

'tis fixed!

…ypescript

blueprint-bot · 2018-01-11T19:17:00Z

Merge branch 'master' of github.com:palantir/blueprint into gg/docs-typescript

Preview: documentation

adidahiya · 2018-01-15T16:54:49Z

packages/docs-theme/src/components/typescript/apiHeader.tsx

+    );
+};
+ApiHeader.contextTypes = DocumentationContextTypes;
+ApiHeader.displayName = "Docs.ApiHeader";


bleh I prefer using React classes over SFCs, especially since code like these 2 lines looks silly. there are literally no benefits to SFCs in practice, and it's easier to "upgrade" components to be more complex as needed when they're classes. but it doesn't have to block this PR

adidahiya · 2018-01-15T16:55:53Z

packages/docs-theme/src/components/typescript/apiHeader.tsx

+            </div>
+            <small className="docs-package-name">
+                <a href={GITHUB_URL + data.fileName.slice(3)} target="__blank">
+                    @blueprintjs/{data.fileName.split("/", 2)[1]}


this needs to be configurable... you're in the docs-theme package, not docs-app

oh snap so true. i think i need to add a url field to the DM data... typedoc already provides one that even links to line number.

oops this is not done. not sure how to support it either...

adidahiya · 2018-01-15T16:56:02Z

packages/docs-theme/src/components/typescript/apiHeader.tsx

+    return `${title} ${array.join(", ")}`;
+}
+
+const GITHUB_URL = "https://github.com/palantir/blueprint/tree/master/packages/";


same here, this needs to be configurable

adidahiya · 2018-01-15T16:56:44Z

packages/docs-theme/src/components/typescript/enumTable.tsx

+    }
+}
+
+// HACKHACK support `code` blocks until we get real markdown parsing in ts-quick-docs


we don't use ts-quick-docs anymore

adidahiya · 2018-01-15T16:57:25Z

packages/docs-theme/src/components/typescript/interfaceTable.tsx

+    }
+}
+
+// HACKHACK support `code` blocks until we get real markdown parsing in ts-quick-docs


another reference to ts-quick-docs

also why is this code duplicated? make it a utility function

adidahiya · 2018-01-15T16:58:45Z

packages/docs-theme/src/tags/defaults.ts

+        heading: tags.Heading,
+        interface: tags.TypescriptExample,
+        page: () => null,
+        // TODO: @see


support the @see tag

i'll address this in the next PR

…typescript

giladgray · 2018-01-23T00:41:37Z

packages/docs-theme/src/components/typescript/apiHeader.tsx

+                </div>
+                <small className="docs-package-name">
+                    <a href={this.props.sourceUrl} target="_blank">
+                        @blueprintjs/{this.props.fileName.split("/", 2)[1]}


@adidahiya thoughts on how to make this configurable? perhaps a new context function getPackageName(entry: ITsDocBase) and some prop on Documentation?

or renderViewSourceLinkText(entry: ITsDocBase): React.ReactNode which defaults to simply returning "View source"

(render...Text cuz the href itself is handled by sourceUrl)

yeah I like the latter approach. default to "View source" and don't do anything too fancy with package paths in this docs-theme package (we can be fancier in docs-app).

blueprint-bot · 2018-01-23T00:44:25Z

markdownCode util

Preview: documentation | landing | table

…typescript

blueprint-bot · 2018-01-25T00:57:16Z

Documentation renderViewSourceLinkText prop

Preview: documentation | landing | table

blueprint-bot · 2018-01-25T00:59:51Z

Merge branch 'develop' of github.com:palantir/blueprint into gg/docs-typescript

Preview: documentation | landing | table

giladgray · 2018-01-25T01:55:39Z

@adidahiya ok I think this is ready to go 🚢

adidahiya

minor comments. -1 for the last one

adidahiya · 2018-01-25T16:36:41Z

packages/docs-theme/src/components/typescript/enumTable.tsx

+    private renderTags(entry: ITsEnumMember) {
+        const { flags: { isDeprecated } } = entry;
+        return (
+            (isDeprecated === true || typeof isDeprecated === "string") && (


not a fan of implicit type coercion and complicated JS inside JSX

adidahiya · 2018-01-25T16:38:50Z

packages/docs-theme/src/components/typescript/interfaceTable.tsx

+        return (
+            <>
+                {!isOptional && <Tag children="Required" className={Classes.MINIMAL} intent={Intent.SUCCESS} />}
+                {(isDeprecated === true || typeof isDeprecated === "string") && (


adidahiya · 2018-01-25T16:40:06Z

packages/docs-theme/src/tags/css.tsx

+    );
+};
+CssExample.contextTypes = DocumentationContextTypes;
+CssExample.displayName = "Docs.CssExample";


prefer making this a class for consistency, since it's complex enough (it requires a helper render function)

adidahiya · 2018-01-25T16:43:58Z

packages/docs-theme/src/tags/reactDocs.tsx

@@ -19,15 +19,15 @@ export class ReactDocsTagRenderer {
     * it to an actual component class in the given map, or in the default map which contains
     * valid docs components from this package. Provide a custom map to inject your own components.
     */
-    public render: TagRenderer = ({ value: componentName }, key) => {
+    public render: React.SFC<ITag> = ({ value: componentName }) => {


why limit this to SFCs? prefer React.ComponentType<ITag>

this is the type of this render function, not the type of the component, so it's actually correct here. but i'll make the change elsewhere to support SFCs in docs components.

see 958dfbd

blueprint-bot · 2018-01-25T19:39:45Z

tag renderers can be SFCs or classes

Preview: documentation | landing | table

Gilad Gray added 8 commits January 9, 2018 14:11

tag renderers are just SFCs!

d7bcf63

remove page arg from renderBlock

add context to Documentation component to expose renderers and docs d…

fd09617

…ata to children

rewrite all tag renderers to be simple SFCs and use context for rende…

1f190f6

…ring

typescript tag supports enums and type aliases too!!

47bf9b6

type IDocsData requires markdown, optional typescript & kss data.

eee719b

ApiHeader component now includes kind, inheritance, package/source link

04c5dfa

don't use ApiLink yet (next PR)

1c9a945

createDefaultRenderers()

50ef8b6

Gilad Gray added 3 commits January 9, 2018 17:40

documentalist 1.0.0-beta.2, add docs-data script to root, fix dev:docs

6f73324

minor code cleanup

46aec7f

tsconfigPath option fixes interface inheritance!!!

8e5c72d

Gilad Gray added 2 commits January 10, 2018 17:35

context docs

a6772e7

Merge branch 'master' of github.com:palantir/blueprint into gg/docs-t…

fd7f4c3

…ypescript

giladgray requested review from themadcreator and adidahiya January 11, 2018 23:21

adidahiya suggested changes Jan 15, 2018

View reviewed changes

adidahiya changed the base branch from master to develop January 15, 2018 17:10

adidahiya mentioned this pull request Jan 18, 2018

[docs] all type aliases should be de-referenced #2020

Closed

Gilad Gray added 3 commits January 22, 2018 16:00

Merge branch 'develop' of github.com:palantir/blueprint into gg/docs-…

71b9f40

…typescript

documentalist beta.4, sourceUrl, react class

b4410ab

markdownCode util

e3e88ee

giladgray commented Jan 23, 2018

View reviewed changes

Documentation renderViewSourceLinkText prop

4b05d99

Gilad Gray added 2 commits January 24, 2018 16:55

Merge branch 'develop' of github.com:palantir/blueprint into gg/docs-…

0a18b3d

…typescript

remove unnecessary dependency

9dc9f97

adidahiya suggested changes Jan 25, 2018

View reviewed changes

Gilad Gray added 3 commits January 25, 2018 11:19

DeprecatedTag SFC

c8fb862

class CssExample

697e48c

tag renderers can be SFCs or classes

958dfbd

adidahiya approved these changes Jan 25, 2018

View reviewed changes

giladgray merged commit 02c4a98 into develop Jan 25, 2018

giladgray deleted the gg/docs-typescript branch January 25, 2018 19:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

improve typescript documentation: enums & aliases! #1982

improve typescript documentation: enums & aliases! #1982

giladgray commented Jan 9, 2018

blueprint-bot commented Jan 9, 2018

giladgray commented Jan 10, 2018

giladgray commented Jan 10, 2018

blueprint-bot commented Jan 10, 2018

giladgray commented Jan 10, 2018

blueprint-bot commented Jan 11, 2018

adidahiya Jan 15, 2018

adidahiya Jan 15, 2018

giladgray Jan 16, 2018

giladgray Jan 23, 2018

adidahiya Jan 15, 2018

adidahiya Jan 15, 2018

adidahiya Jan 15, 2018

adidahiya Jan 15, 2018

adidahiya Jan 15, 2018

giladgray Jan 16, 2018

giladgray Jan 25, 2018

giladgray Jan 23, 2018

giladgray Jan 23, 2018 •

edited

Loading

adidahiya Jan 23, 2018

blueprint-bot commented Jan 23, 2018

blueprint-bot commented Jan 25, 2018

blueprint-bot commented Jan 25, 2018

giladgray commented Jan 25, 2018

adidahiya left a comment

adidahiya Jan 25, 2018

adidahiya Jan 25, 2018

adidahiya Jan 25, 2018

adidahiya Jan 25, 2018

giladgray Jan 25, 2018 •

edited

Loading

blueprint-bot commented Jan 25, 2018

improve typescript documentation: enums & aliases! #1982

improve typescript documentation: enums & aliases! #1982

Conversation

giladgray commented Jan 9, 2018

Changes proposed in this pull request:

Reviewers should focus on:

blueprint-bot commented Jan 9, 2018

createDefaultRenderers()

giladgray commented Jan 10, 2018

giladgray commented Jan 10, 2018

blueprint-bot commented Jan 10, 2018

tsconfigPath option fixes interface inheritance!!!

giladgray commented Jan 10, 2018

blueprint-bot commented Jan 11, 2018

Merge branch 'master' of github.com:palantir/blueprint into gg/docs-typescript

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 Jan 23, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

blueprint-bot commented Jan 23, 2018

markdownCode util

blueprint-bot commented Jan 25, 2018

Documentation renderViewSourceLinkText prop

blueprint-bot commented Jan 25, 2018

Merge branch 'develop' of github.com:palantir/blueprint into gg/docs-typescript

giladgray commented Jan 25, 2018

adidahiya 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

giladgray Jan 25, 2018 • edited Loading

Choose a reason for hiding this comment

blueprint-bot commented Jan 25, 2018

tag renderers can be SFCs or classes

giladgray Jan 23, 2018 •

edited

Loading

giladgray Jan 25, 2018 •

edited

Loading