[Canvas] Adds function reference docs generator by cqliu1 · Pull Request #49402 · elastic/kibana

cqliu1 · 2019-10-25T20:32:54Z

Summary

This adds a button to the global nav help menu in the Canvas app for developers to generate the function reference. This button only appears in development, so it's not a user-facing feature.

Once you click the button, the entire markdown content of the function reference docs will be stored to your clipboard, and then you'll have to navigate to kibana/docs/canvas/canvas-function-reference.asciidoc and paste in the generated content.

Because all of our function definitions support i18n, we have to generate the docs while Kibana is running, so I couldn't create a nice script to generate the docs and write the changes to the asciidoc file directly. This is a clunky workflow, but since it's not user-facing, I think it works well enough to get the job done. I'm open to suggestions for a better UX.

Checklist

Use ~~strikethroughs~~ to remove checklist items you don't feel are applicable to this PR.

For maintainers

This was checked for breaking API changes and was labeled appropriately
This includes a feature addition or change that requires a release note and was labeled appropriately

elasticmachine · 2019-10-25T21:54:00Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request
Commit: c256ab7cdceaab7b78518dfc67c2c8ca35831d0b

elasticmachine · 2019-10-26T01:48:05Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 7dc0d3c0b9f5a3b4ecbfbf561dbf83a136c0aa22

elasticmachine · 2019-10-26T03:48:53Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 7c0eff797b628fd53e38b0e9fc46f1f155f2030e

elasticmachine · 2019-10-26T15:46:54Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 8acb0496f5bc6b54ea637f47e5e9e189cfdff206

elasticmachine · 2019-10-28T22:59:50Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 1c6f54fd2da2678f8f0206d31a7428eaf0341cf1

elasticmachine · 2019-10-28T23:41:56Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: d6150b8c25b17501cd40d9974aacdc9ccb42c1e2

elasticmachine · 2019-10-29T18:19:44Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: f00245830e2f57a16f216bdf3b61ae40f046653f

elasticmachine · 2019-10-29T20:31:39Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: b58b9ebfaab2007f1568dc7399b00ccb086eb04b

elasticmachine · 2019-10-29T22:52:40Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 9add68142f5f11f851fd4b266371452fa2ce2c3b

elasticmachine · 2019-10-30T20:48:07Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 42a0ff7b48deca0a25ff1d36234feaaa9b708239

elasticmachine · 2019-10-31T18:40:17Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 9de4e419963bf79d9a7a228bb5356b8453224521

elasticmachine · 2019-10-31T19:24:56Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 042377d61bb43f3f146e751c17c76034abd222ad

elasticmachine · 2019-11-11T17:46:52Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: f39320145d4b05cfc40e4a9c6cb16e4305a23cd7

lukeelmers

@cqliu1 I know this is just in draft state, but I'll leave a few notes as a follow up from our offline conversations last week. If you are looking for a final review once this is out of draft, feel free to request me and I'd be happy to run it locally and test it out.

Overall I don't think it matters exactly how this is implemented right now, since the only use for these is Canvas autocomplete. If we were to officially expose this example data as part of the larger public expressions service, I'd want to think more about whether the function definition is the right place to introduce arbitrary metadata like this.

Functionally, this metadata exists solely for the purposes of displaying content in the UI... it doesn't have anything to do with how the function is handled by the interpreter. So on the one hand, I like the idea of trying to separate these concerns. But on the other hand, I don't know that a separate "examples registry" or whatever is the most elegant way to go about this longer term; this is something we'd need to explore further if we see more and more use cases like this popping up.

For the time being, I have no major concerns on my end as long as we are clearly marking this portion of the interface as "internal" and for use in Canvas only... that way we have flexibility to change things up later if needed.

cc @ppisljar I think this is in line with what we discussed too, feel free to add anything I've missed.

x-pack/legacy/plugins/canvas/canvas_plugin_src/functions/common/join_rows.ts

x-pack/legacy/plugins/canvas/i18n/functions/dict/compare.ts

x-pack/legacy/plugins/canvas/public/components/help_menu/help_menu.js

src/plugins/expressions/public/types/functions.ts

x-pack/legacy/plugins/canvas/canvas_plugin_src/functions/common/if.ts

src/plugins/expressions/public/types/functions.ts

x-pack/legacy/plugins/canvas/public/components/help_menu/function_reference_generator.tsx

src/plugins/expressions/public/types/functions.ts

elasticmachine · 2019-11-14T20:55:01Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request
Commit: 3261b2c3f0b293d6986b0c16ba7475536dcd42b9

poffdeluxe

overall stuff looks good -- I did find an issue with that str.contains stuff though and I have a few nits. Also, a functional test would be great if possible

...ugins/canvas/public/components/function_reference_generator/function_reference_generator.tsx

x-pack/plugins/canvas/public/components/help_menu/help_menu.js

poffdeluxe · 2020-08-04T21:31:01Z

...ugins/canvas/public/components/function_reference_generator/function_reference_generator.tsx

+${createFunctionDocs(functionDictionary)}`;
+};
+
+const createAlphabetLinks = (functionDictionary: FunctionDictionary) => {


nit: might make sense to put all these helper funcs into a lib or something somewhere. Feels a bit big for a component file

I extract all the doc related functions into a separate file in the same component folder.

...ugins/canvas/public/components/function_reference_generator/function_reference_generator.tsx

Move FunctionGenerator component to lazy loaded bundle

…nto docs/function-ref-script

kibanamachine · 2020-08-24T17:37:44Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request
Commit: 3f55eeb

Build metrics

async chunks size

id	value	diff	baseline
canvas	1.4MB	-1.2KB	1.4MB

page load bundle size

id	value	diff	baseline
canvas	1.3MB	+527.0B	1.3MB

History

💚 Build #69451 succeeded 40afdae
💔 Build #68800 failed e7d34b9
💔 Build #66695 failed c639ace
💔 Build #66498 failed e095781
💔 Build #66466 failed fb20cf7

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

Co-authored-by: Corey Robertson <corey.robertson@elastic.co> # Conflicts: # x-pack/plugins/canvas/i18n/functions/dict/map_column.ts

cqliu1 force-pushed the docs/function-ref-script branch 2 times, most recently from 0609fc7 to c256ab7 Compare October 25, 2019 20:39

cqliu1 force-pushed the docs/function-ref-script branch from c256ab7 to 41d8e23 Compare October 26, 2019 00:02

cqliu1 changed the title ~~[Canvas] Adds script for generating function reference docs~~ [Canvas] Adds function reference docs generator Oct 26, 2019

cqliu1 force-pushed the docs/function-ref-script branch 5 times, most recently from 1e54f15 to 59e3215 Compare October 26, 2019 01:29

cqliu1 force-pushed the docs/function-ref-script branch from fc1dcd5 to b58b9eb Compare October 29, 2019 19:26

cqliu1 force-pushed the docs/function-ref-script branch from 1ddbd5a to 9add681 Compare October 29, 2019 21:32

cqliu1 force-pushed the docs/function-ref-script branch from e5f6d12 to b98f061 Compare October 31, 2019 16:38

cqliu1 force-pushed the docs/function-ref-script branch from 042377d to f393201 Compare November 11, 2019 16:18

lukeelmers reviewed Nov 11, 2019

View reviewed changes

cqliu1 mentioned this pull request Nov 12, 2019

[Canvas][Docs] Updates function reference #50393

Merged

4 tasks

cqliu1 force-pushed the docs/function-ref-script branch from f393201 to 3261b2c Compare November 14, 2019 19:37

cqliu1 added 6 commits August 4, 2020 09:39

Fixed spacing

8e80ccc

Fixes typos

b9cdf42

Fixed pie strings

b5aee0b

Fixed ts errors

9f10935

Fixed typos

d947710

Added var and var_set

c70fe29

cqliu1 force-pushed the docs/function-ref-script branch from ffe344e to c70fe29 Compare August 4, 2020 16:45

cqliu1 added 3 commits August 4, 2020 10:44

Removed var and var_set from doc updates

fe4a2d8

Updated helper fn

a02c46d

Restore quotes to default values

fb20cf7

poffdeluxe approved these changes Aug 4, 2020

View reviewed changes

poffdeluxe reviewed Aug 4, 2020

View reviewed changes

...ugins/canvas/public/components/function_reference_generator/function_reference_generator.tsx Outdated Show resolved Hide resolved

cqliu1 and others added 10 commits August 4, 2020 15:06

Applied feedback

d103aaa

Added value to location help text

e095781

Move FunctionGenerator component to lazy loaded bundle

0e88aad

Merge pull request #13 from crob611/pr/49402

c639ace

Move FunctionGenerator component to lazy loaded bundle

Merge branch 'master' into docs/function-ref-script

819952c

Merge branch 'docs/function-ref-script' of github.com:cqliu1/kibana i…

e7d34b9

…nto docs/function-ref-script

Fixed i18n errors

0d95970

Fixed ts errors

62c2cf5

Merge branch 'master' into docs/function-ref-script

40afdae

Merge branch 'master' into docs/function-ref-script

3f55eeb

cqliu1 merged commit 3256992 into elastic:master Aug 24, 2020

cqliu1 deleted the docs/function-ref-script branch August 24, 2020 21:28

cqliu1 removed the v7.9.0 label Aug 24, 2020

cqliu1 mentioned this pull request Aug 24, 2020

[7.x] [Canvas] Adds function reference docs generator (#49402) #75831

Merged

cqliu1 added a commit that referenced this pull request Aug 25, 2020

[Canvas] Adds function reference docs generator (#49402) (#75831)

5830101

Co-authored-by: Corey Robertson <corey.robertson@elastic.co> # Conflicts: # x-pack/plugins/canvas/i18n/functions/dict/map_column.ts

cqliu1 restored the docs/function-ref-script branch June 8, 2022 14:01

Conversation

cqliu1 commented Oct 25, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Checklist

For maintainers

Uh oh!

elasticmachine commented Oct 25, 2019

💚 Build Succeeded

Uh oh!

elasticmachine commented Oct 26, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 26, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 26, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 28, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 28, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 29, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 29, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 29, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 30, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 31, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Oct 31, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Nov 11, 2019

💔 Build Failed

Uh oh!

lukeelmers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elasticmachine commented Nov 14, 2019

💔 Build Failed

Uh oh!

poffdeluxe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

poffdeluxe Aug 4, 2020

Choose a reason for hiding this comment

Uh oh!

cqliu1 Aug 4, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kibanamachine commented Aug 24, 2020

💚 Build Succeeded

Build metrics

async chunks size

page load bundle size

History

Uh oh!

Reviewers

cqliu1 commented Oct 25, 2019 •

edited

Loading