Add codesandbox links to our documentation #2728

snide · 2020-01-02T23:04:38Z

Summary

Adds dynamic code sandbox docs to our documentation.

How it works

Using a bunch of regex, any src-doc example gets built into a reformatted index.js file and uploaded to code sandbox that is told to use the latest version of our dependencies.
In special cases like form examples, it also adds the display toggles component, which is used it a lot of our examples.
If it sees a simple outside dependency imported into one of our docs example (like faker in data grid) it will add it to the sandbox.

Limitations

If our src-doc examples get complicated and include internal components for the docs (say a helper file to generate content for the example) then we don't generate a link. The regex checks are smart enough to make this decision automatically. I don't think we want to recursively run regex on imported files.
The exception to the above is examples using display toggles. Since we lean on that toggle system quite a bit I went ahead and added some extra logic to check if the example includes them and then tell codesandbox to generate an imported file for them. This again, happens automatically and should be carry over changes we make to any of those files.
Currently only works for JS src-doc examples. We have a couple TS docs files. It gracefully fails.
This requires docs examples to export as default functions. I've changed any that weren't to make them work and match our more common style for docs.

Here is a list of examples that don't work and the reason. We should clean these up in separate PRs.

🙈 = doesn't show a link to CS, no one will see it break
💔 = brittle regex causes an error in CS

🙈 EuiHeader, EuiNavDrawer, EuiCollapsableNav, EuiColorPalette, EuiFocusTrap, EuiWindowEvent uses helper docs includes that should be moved to the example code.
🙈 EuiTable uses special includes that could likely be switched to faker
🙈 EuiHorizontalRule, EuiSpacer, EuiCommentList, EuiSelectable, EuiScreenReadOnly demo examples are TypeScript files.
🙈 EuiToastList uses a non-standard way to build the example page.
~~💔 EuiCodeEditor breaks because of the way we import Brace deps~~
🙈 EuiSearchBar has a bunch of hidden docs utils that are included in src and screw up the imports. They should be replaced with doc level functions.
🙈 Elastic Charts examples need something custom and have no links.

For review

This includes a lot of regex, some of which is written by your lowly narratar! Besides regex being fairly brittle, I'd appreciate a check on the patterns I'm using to make sure they are fairly tolerant to change.

Checklist

Check against all themes for compatibility in both light and dark modes
Checked in mobile
Checked in IE11 and Firefox
Props have proper autodocs
Added documentation examples
Added or updated jest tests
Checked for breaking changes and labeled appropriately
Checked for accessibility including keyboard-only and screenreader modes
A changelog entry exists and is marked appropriately

…page

snide · 2020-01-12T18:00:10Z

src-docs/src/views/facet/facet_layout.js

@@ -9,7 +9,7 @@ import {
  EuiSpacer,
 } from '../../../../src/components';

-import { VISUALIZATION_COLORS } from '../../../../src/services/color/visualization_colors';


Should we deprecate this now that we have real palettes?

I thought about that too as I was messing with the palettes and I don't think it makes sense to have two ways to export the viz palette.

Cool. I'll add it to our list then. They are definitely duplicative, and the new one is a more reliable method of pulling those values.

snide · 2020-01-12T18:02:18Z

src-docs/src/services/string/clean_imports.js

+    .map(x => x.groups.import)
+    .reduce((deps, dep) => {
+      // Hack because the docs are locked to a specific version of React Router
+      deps[dep] = dep === 'react-router' ? '^3.2.5' : 'latest';


Couldn't think of a way to pull this from package.json automatically?

const pkg = require('../../../../package.json'); at the top of the file
and then replace '^3.2.5' with pkg.devDependencies['react-router']

snide · 2020-01-12T18:03:23Z

src-docs/src/views/flex/flex_group.tsx

+  EuiFlexGroup,
+  EuiFlexItem,
+  EuiSpacer,
+  // @ts-ignore


Gotta follow up on why this was needed.

I don't think this is necessary

^^ Can delete now?

miukimiu · 2020-01-17T16:34:25Z

Hi @snide,

I was thinking if we could have the Codesandbox icon next to the fullscreen icon. I know the fullscreen icon is part of the EuiCodeBlock but maybe is something to think for the future.

snide · 2020-01-17T17:01:16Z

@miukimiu That was my original idea, but people liked the discreet link. I was thinking to add a new prop to EuiCodeBlock for extraControls or something, so you could put other stuff in there.

Easy enough to change if others feel the same, but I'll let the PR get reviews / merged first on all the regex crazyness first before getting to fiddly with the design.

thompsongl

Icons actually throw errors (not just not render). Is this what you've seen also?

Accordion demo:

thompsongl · 2020-01-31T17:18:21Z

src-docs/src/views/flex/flex_group.tsx

+  EuiFlexGroup,
+  EuiFlexItem,
+  EuiSpacer,
+  // @ts-ignore


I don't think this is necessary

thompsongl · 2020-01-31T17:24:26Z

src-docs/src/services/string/clean_imports.js

+    .map(x => x.groups.import)
+    .reduce((deps, dep) => {
+      // Hack because the docs are locked to a specific version of React Router
+      deps[dep] = dep === 'react-router' ? '^3.2.5' : 'latest';


const pkg = require('../../../../package.json'); at the top of the file
and then replace '^3.2.5' with pkg.devDependencies['react-router']

snide · 2020-01-31T17:41:40Z

@thompsongl Looks like it's something happening only in the last couple versions of EUI. Checking it out. You can replicate by moving the EUI req away from latest.

kibanamachine · 2020-06-02T05:45:34Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_2728/

kibanamachine · 2020-06-02T16:10:08Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_2728/

snide · 2020-06-03T17:15:53Z

This is mostly reviewable if folks want to poke around. I think the EuiCodeEditor example is the only one I think needs to get fixed.

src-docs/src/services/string/clean_imports.js

kibanamachine · 2020-06-03T20:18:06Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_2728/

miukimiu · 2020-06-04T12:37:03Z

I think we have an issue with all the pages using a DisplayToggles.

The exception to the above is examples using display toggles. Since we lean on that toggle system quite a bit I went ahead and added some extra logic to check if the example includes them and then tell codesandbox to generate an imported file for them. This again, happens automatically and should be carry over changes we make to any of those files.

I noticed that this is not working as expected. The file is generated correctly but the import { DisplayToggles } from './display_toggles'; fails.

For example, you can try the first example which uses a DisplayToggles on the EuiComboBox page:
https://eui.elastic.co/pr_2728/#/forms/combo-box

It throws the following error:

Here's another example (Date picker states):
https://eui.elastic.co/pr_2728/#/forms/date-picker

chandlerprall · 2020-06-04T20:56:56Z

I've pushed a fix for the display toggle import issue, but trying to render the toggles gives this error:

Invariant failed: You should not use outside a

because display_toggles.js has <Link to="/forms/compressed-forms">

cchaos · 2020-06-04T20:58:29Z

I think eventually the "Playground" will allow us to get rid of the DisplayToggles. Perhaps just ignore all those examples for now?

snide · 2020-06-04T21:16:58Z

I had them working before these latest commits / changes from CS. I'll double check on them and see what's up. It touches a lot of our examples, so i wanted to make sure they worked.

kibanamachine · 2020-06-04T21:20:30Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_2728/

snide · 2020-06-04T21:53:03Z

OK. Fix was to just not use react-router for that link, an use a simple href. It acts as it did before. Ultimately we can use playgrounds for this stuff, but for the moment I think it's really important to spin up a CS for any form element really quicky, which is why I think it's worth the very minor inconvenience of having to use an href there.

snide · 2020-06-04T21:59:38Z

@cchaos also added a notice in our PR template as we mentioned. I think this one looks good to merge. TY to @chandlerprall for the regex fix.

cchaos

👍 Aside from the awesomeness of quickly getting to edit the example, I like that the home page link to Codesandbox is now super generic, that faker works, and TS docs can import from /components now. 🥳

cchaos · 2020-06-04T22:18:33Z

src-docs/src/views/flex/flex_group.tsx

+  EuiFlexGroup,
+  EuiFlexItem,
+  EuiSpacer,
+  // @ts-ignore


^^ Can delete now?

kibanamachine · 2020-06-04T22:23:49Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_2728/

…-router hack

kibanamachine · 2020-06-04T23:28:58Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_2728/

snide · 2020-06-04T23:44:24Z

retest

kibanamachine · 2020-06-05T00:05:41Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_2728/

snide · 2020-06-05T01:12:26Z

This is passing, and I think I've gotten to the feedback. I'm going to do a merge since this one touches so many files and I want to avoid conflicts. Since it's a docs level change I think this is pretty safe.

snide added 17 commits December 20, 2019 15:21

initial work for cs support

795ed53

cleanup

ab3374e

Merge remote-tracking branch 'upstream/master' into demo/sandbox

1f1b563

fixes for formatting and flyouts

c461a52

remove codesanboxer, it's not needed

b8816ce

derp, fix yarn lock too

1707334

fix tree view, adjust regex

5a499a9

make a component for code sandbox links, fix the link from the front …

1ab85a8

…page

don't show code sandbox demos if it has local doc imports

2eeb0d2

small fixes

da51808

Merge remote-tracking branch 'upstream/master' into demo/sandbox

d23bc4d

Merge remote-tracking branch 'upstream/master' into demo/sandbox

447dcf0

better notice about icons

9dbce9e

Merge remote-tracking branch 'upstream/master' into demo/sandbox

adcd16f

Fixes for examples

7bf2773

with dumb hacks display toggles now work on codesanbox examples

5da2925

cleaned up the code to be readible and less brittle

1bce0d7

snide marked this pull request as ready for review January 12, 2020 17:55

snide changed the title ~~[WIP] Add codesandbox links to our documentation~~ Add codesandbox links to our documentation Jan 12, 2020

snide commented Jan 12, 2020

View reviewed changes

snide added 2 commits January 12, 2020 10:07

fix from cleanup

99b56cf

forgot to clean my homepage link

a5fc03f

chandlerprall self-requested a review January 13, 2020 16:04

snide mentioned this pull request Jan 17, 2020

[Meta] Environments/Projects we want to intentionally support #2760

Closed

thompsongl reviewed Jan 31, 2020

View reviewed changes

fix resizable lorem stuff

cf8deed

snide requested a review from miukimiu June 3, 2020 16:22

snide commented Jun 3, 2020

View reviewed changes

src-docs/src/services/string/clean_imports.js Outdated Show resolved Hide resolved

chandlerprall added 2 commits June 3, 2020 13:41

Fix imports for codesandbox link in EuiCodeEditor

2d07371

Merge branch 'master' into demo/sandbox

da56301

Fix import inspect/extract regex from looking at relative imports

866a4ba

snide added 2 commits June 4, 2020 14:50

replace toggle with an href link

fb429d9

Merge remote-tracking branch 'upstream/master' into demo/sandbox

9be85c0

snide added 2 commits June 4, 2020 14:57

CS mention in PR request template

bb6e08e

CS mention in PR request template

a4a1b4c

cchaos approved these changes Jun 4, 2020

View reviewed changes

address greg's feedback, break up the ts import, and remove the react…

2788678

…-router hack

snide merged commit 9d54fd5 into elastic:master Jun 5, 2020

snide deleted the demo/sandbox branch June 5, 2020 01:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add codesandbox links to our documentation #2728

Add codesandbox links to our documentation #2728

snide commented Jan 2, 2020 •

edited

Loading

snide Jan 12, 2020

cchaos Jan 13, 2020

snide Jan 13, 2020

snide Jan 12, 2020

thompsongl Jan 31, 2020

snide Jan 12, 2020

thompsongl Jan 31, 2020

cchaos Jun 4, 2020

miukimiu commented Jan 17, 2020

snide commented Jan 17, 2020

thompsongl left a comment

thompsongl Jan 31, 2020

thompsongl Jan 31, 2020

snide commented Jan 31, 2020 •

edited

Loading

kibanamachine commented Jun 2, 2020

kibanamachine commented Jun 2, 2020

snide commented Jun 3, 2020

kibanamachine commented Jun 3, 2020

miukimiu commented Jun 4, 2020 •

edited

Loading

chandlerprall commented Jun 4, 2020

cchaos commented Jun 4, 2020

snide commented Jun 4, 2020

kibanamachine commented Jun 4, 2020

snide commented Jun 4, 2020

snide commented Jun 4, 2020

cchaos left a comment

cchaos Jun 4, 2020

kibanamachine commented Jun 4, 2020

kibanamachine commented Jun 4, 2020

snide commented Jun 4, 2020

kibanamachine commented Jun 5, 2020

snide commented Jun 5, 2020

Add codesandbox links to our documentation #2728

Add codesandbox links to our documentation #2728

Conversation

snide commented Jan 2, 2020 • edited Loading

Summary

How it works

Limitations

For review

Checklist

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

miukimiu commented Jan 17, 2020

snide commented Jan 17, 2020

thompsongl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snide commented Jan 31, 2020 • edited Loading

kibanamachine commented Jun 2, 2020

kibanamachine commented Jun 2, 2020

snide commented Jun 3, 2020

kibanamachine commented Jun 3, 2020

miukimiu commented Jun 4, 2020 • edited Loading

chandlerprall commented Jun 4, 2020

cchaos commented Jun 4, 2020

snide commented Jun 4, 2020

kibanamachine commented Jun 4, 2020

snide commented Jun 4, 2020

snide commented Jun 4, 2020

cchaos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibanamachine commented Jun 4, 2020

kibanamachine commented Jun 4, 2020

snide commented Jun 4, 2020

kibanamachine commented Jun 5, 2020

snide commented Jun 5, 2020

snide commented Jan 2, 2020 •

edited

Loading

snide commented Jan 31, 2020 •

edited

Loading

miukimiu commented Jun 4, 2020 •

edited

Loading