From 58f10e0c92572d57b24fe14f7e52f39295f7bf01 Mon Sep 17 00:00:00 2001 From: Nathan Reese Date: Wed, 24 Jan 2018 15:52:19 -0700 Subject: [PATCH 1/7] tutorial docs --- STYLEGUIDE.md | 1 + style_guides/add_data_tutorial_guide.md | 27 +++++++++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 style_guides/add_data_tutorial_guide.md diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 90860721357a1..f148a664164b7 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -12,6 +12,7 @@ recommended for the development of all Kibana plugins. - [API](style_guides/api_style_guide.md) - [Architecture](style_guides/architecture_style_guide.md) - [Accessibility](style_guides/accessibility_guide.md) +- [Add Data tutorial](style_guides/add_data_tutorial_guide.md) ## Filenames diff --git a/style_guides/add_data_tutorial_guide.md b/style_guides/add_data_tutorial_guide.md new file mode 100644 index 0000000000000..c5c74ebc77413 --- /dev/null +++ b/style_guides/add_data_tutorial_guide.md @@ -0,0 +1,27 @@ +# Add Data guide +`Add Data` in the Kibana Home application contains a collection of tutorials for setting up data flows in the Elastic stack. + +Each tutorial contains 3 sets of instructions +1. `On Premise` Instructions for setting up a data flow when both Kibana and Elastic Search are running on premise +2. `On Premise Elastic Cloud` Instructions for setting up a data flow when Kibana is running on premise but +Elastic Search is running on cloud. +3. `Elastic Cloud` Instructions for setting up a data flow when both Kibana and Elastic Search are running on cloud. + +## Creating a new tutorial +1. Create a new folder in the [tutorials directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/server/tutorials). +2. In the new folder, create a file called `index.js` that exports a function. +The function must return a Javascript object that conforms to the [tutorial schema](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/common/tutorials/tutorial_schema.js). +3. Register the tutorial in [register.js](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/server/tutorials/register.js) by calling `server.registerTutorial(myFuncImportedFromIndexJs)`. +4. Add image assets to the [tutorial_resources directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/public/home/tutorial_resources). +5. Create a PR and go through the review process to get the changes approved. + +### Variables +String values can contain variables that get substituted when rendered. Variables are specified by `{}`. +For example: `{config.docs.version}` would get rendered as `6.2` when running the tutorial in Kibana 6.2. + +[Provided variables](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/replace_template_strings.js#L23) + +### Markdown +String values can contain limited markdown syntax. + +[Enabled markdown grammers](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/content.js#L8) From 2892b714053ccbe3acaa3a8b07a1fea7997045a7 Mon Sep 17 00:00:00 2001 From: Nathan Reese Date: Thu, 25 Jan 2018 08:32:33 -0700 Subject: [PATCH 2/7] fixes from ycombinator review --- style_guides/add_data_tutorial_guide.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/style_guides/add_data_tutorial_guide.md b/style_guides/add_data_tutorial_guide.md index c5c74ebc77413..4240020f69017 100644 --- a/style_guides/add_data_tutorial_guide.md +++ b/style_guides/add_data_tutorial_guide.md @@ -2,18 +2,19 @@ `Add Data` in the Kibana Home application contains a collection of tutorials for setting up data flows in the Elastic stack. Each tutorial contains 3 sets of instructions -1. `On Premise` Instructions for setting up a data flow when both Kibana and Elastic Search are running on premise +1. `On Premise` Instructions for setting up a data flow when both Kibana and ElasticSearch are running on premise 2. `On Premise Elastic Cloud` Instructions for setting up a data flow when Kibana is running on premise but -Elastic Search is running on cloud. -3. `Elastic Cloud` Instructions for setting up a data flow when both Kibana and Elastic Search are running on cloud. +ElasticSearch is running on cloud. +3. `Elastic Cloud` Instructions for setting up a data flow when both Kibana and ElasticSearch are running on cloud. ## Creating a new tutorial -1. Create a new folder in the [tutorials directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/server/tutorials). -2. In the new folder, create a file called `index.js` that exports a function. +1. Create a new directory in the [tutorials directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/server/tutorials). +2. In the new directory, create a file called `index.js` that exports a function. The function must return a Javascript object that conforms to the [tutorial schema](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/common/tutorials/tutorial_schema.js). 3. Register the tutorial in [register.js](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/server/tutorials/register.js) by calling `server.registerTutorial(myFuncImportedFromIndexJs)`. 4. Add image assets to the [tutorial_resources directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/public/home/tutorial_resources). -5. Create a PR and go through the review process to get the changes approved. +5. Run Kibana locally to preview the tutorial. +6. Create a PR and go through the review process to get the changes approved. ### Variables String values can contain variables that get substituted when rendered. Variables are specified by `{}`. @@ -24,4 +25,4 @@ For example: `{config.docs.version}` would get rendered as `6.2` when running th ### Markdown String values can contain limited markdown syntax. -[Enabled markdown grammers](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/content.js#L8) +[Enabled markdown grammars](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/content.js#L8) From 7889b0277c7fe0aa383e2904f8c0377b3cc25559 Mon Sep 17 00:00:00 2001 From: Nathan Reese Date: Thu, 25 Jan 2018 08:46:41 -0700 Subject: [PATCH 3/7] ElasticSearch -> Elasticsearch --- style_guides/add_data_tutorial_guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/style_guides/add_data_tutorial_guide.md b/style_guides/add_data_tutorial_guide.md index 4240020f69017..613617a70e5b5 100644 --- a/style_guides/add_data_tutorial_guide.md +++ b/style_guides/add_data_tutorial_guide.md @@ -2,10 +2,10 @@ `Add Data` in the Kibana Home application contains a collection of tutorials for setting up data flows in the Elastic stack. Each tutorial contains 3 sets of instructions -1. `On Premise` Instructions for setting up a data flow when both Kibana and ElasticSearch are running on premise +1. `On Premise` Instructions for setting up a data flow when both Kibana and Elasticsearch are running on premise 2. `On Premise Elastic Cloud` Instructions for setting up a data flow when Kibana is running on premise but -ElasticSearch is running on cloud. -3. `Elastic Cloud` Instructions for setting up a data flow when both Kibana and ElasticSearch are running on cloud. +Elasticsearch is running on cloud. +3. `Elastic Cloud` Instructions for setting up a data flow when both Kibana and Elasticsearch are running on cloud. ## Creating a new tutorial 1. Create a new directory in the [tutorials directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/server/tutorials). From 590e10a964c680dd8e628ed529a67e6b00287172 Mon Sep 17 00:00:00 2001 From: Nathan Reese Date: Thu, 25 Jan 2018 09:03:05 -0700 Subject: [PATCH 4/7] move out of style guide and into README under server/tutorials --- STYLEGUIDE.md | 1 - .../core_plugins/kibana/server/tutorials/README.md | 0 2 files changed, 1 deletion(-) rename style_guides/add_data_tutorial_guide.md => src/core_plugins/kibana/server/tutorials/README.md (100%) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index f148a664164b7..90860721357a1 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -12,7 +12,6 @@ recommended for the development of all Kibana plugins. - [API](style_guides/api_style_guide.md) - [Architecture](style_guides/architecture_style_guide.md) - [Accessibility](style_guides/accessibility_guide.md) -- [Add Data tutorial](style_guides/add_data_tutorial_guide.md) ## Filenames diff --git a/style_guides/add_data_tutorial_guide.md b/src/core_plugins/kibana/server/tutorials/README.md similarity index 100% rename from style_guides/add_data_tutorial_guide.md rename to src/core_plugins/kibana/server/tutorials/README.md From 46a1405a5802ff863d60943479910770af1e3922 Mon Sep 17 00:00:00 2001 From: Nathan Reese Date: Thu, 25 Jan 2018 09:39:11 -0700 Subject: [PATCH 5/7] move to asciidocs --- .../development/add-data-guide.asciidoc | 26 ++++++++++++------- docs/development/plugin-development.asciidoc | 5 +++- 2 files changed, 20 insertions(+), 11 deletions(-) rename src/core_plugins/kibana/server/tutorials/README.md => docs/development/add-data-guide.asciidoc (50%) diff --git a/src/core_plugins/kibana/server/tutorials/README.md b/docs/development/add-data-guide.asciidoc similarity index 50% rename from src/core_plugins/kibana/server/tutorials/README.md rename to docs/development/add-data-guide.asciidoc index 613617a70e5b5..403ecff6d5c15 100644 --- a/src/core_plugins/kibana/server/tutorials/README.md +++ b/docs/development/add-data-guide.asciidoc @@ -1,4 +1,6 @@ -# Add Data guide +[[add-data-guide]] +== Add Data guide + `Add Data` in the Kibana Home application contains a collection of tutorials for setting up data flows in the Elastic stack. Each tutorial contains 3 sets of instructions @@ -7,22 +9,26 @@ Each tutorial contains 3 sets of instructions Elasticsearch is running on cloud. 3. `Elastic Cloud` Instructions for setting up a data flow when both Kibana and Elasticsearch are running on cloud. -## Creating a new tutorial -1. Create a new directory in the [tutorials directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/server/tutorials). +[float] +=== Creating a new tutorial +1. Create a new directory in the link:https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/server/tutorials[tutorials directory]. 2. In the new directory, create a file called `index.js` that exports a function. -The function must return a Javascript object that conforms to the [tutorial schema](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/common/tutorials/tutorial_schema.js). -3. Register the tutorial in [register.js](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/server/tutorials/register.js) by calling `server.registerTutorial(myFuncImportedFromIndexJs)`. -4. Add image assets to the [tutorial_resources directory](https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/public/home/tutorial_resources). +The function must return a Javascript object that conforms to the link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/common/tutorials/tutorial_schema.js[tutorial schema]. +3. Register the tutorial in link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/server/tutorials/register.js[register.js] by calling `server.registerTutorial(myFuncImportedFromIndexJs)`. +4. Add image assets to the link:https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/public/home/tutorial_resources[tutorial_resources directory]. 5. Run Kibana locally to preview the tutorial. 6. Create a PR and go through the review process to get the changes approved. -### Variables +[float] +==== Variables String values can contain variables that get substituted when rendered. Variables are specified by `{}`. For example: `{config.docs.version}` would get rendered as `6.2` when running the tutorial in Kibana 6.2. -[Provided variables](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/replace_template_strings.js#L23) +link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/replace_template_strings.js#L23[Provided variables] -### Markdown +[float] +==== Markdown String values can contain limited markdown syntax. -[Enabled markdown grammars](https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/content.js#L8) +link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/content.js#L8[Enabled markdown grammars] + diff --git a/docs/development/plugin-development.asciidoc b/docs/development/plugin-development.asciidoc index 0f0c2e2f54172..6167c8a195a64 100644 --- a/docs/development/plugin-development.asciidoc +++ b/docs/development/plugin-development.asciidoc @@ -10,6 +10,7 @@ The Kibana plugin interfaces are in a state of constant development. We cannot * <> * <> * <> +* <> include::plugin/development-plugin-resources.asciidoc[] @@ -18,4 +19,6 @@ include::plugin/development-uiexports.asciidoc[] include::plugin/development-plugin-functional-tests.asciidoc[] -include::visualize/development-visualize-index.asciidoc[] \ No newline at end of file +include::visualize/development-visualize-index.asciidoc[] + +include::add-data-guide.asciidoc[] From c81c5e5b0ca6f88a516c48504e7039b2aedb7406 Mon Sep 17 00:00:00 2001 From: Nathan Reese Date: Thu, 25 Jan 2018 09:42:46 -0700 Subject: [PATCH 6/7] add new line so list is rendered correctly --- docs/development/add-data-guide.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/development/add-data-guide.asciidoc b/docs/development/add-data-guide.asciidoc index 403ecff6d5c15..0e085954818d2 100644 --- a/docs/development/add-data-guide.asciidoc +++ b/docs/development/add-data-guide.asciidoc @@ -4,6 +4,7 @@ `Add Data` in the Kibana Home application contains a collection of tutorials for setting up data flows in the Elastic stack. Each tutorial contains 3 sets of instructions + 1. `On Premise` Instructions for setting up a data flow when both Kibana and Elasticsearch are running on premise 2. `On Premise Elastic Cloud` Instructions for setting up a data flow when Kibana is running on premise but Elasticsearch is running on cloud. From 5592d2842ebe7d5b2b91b3a1857762e9ce85c17c Mon Sep 17 00:00:00 2001 From: Nathan Reese Date: Thu, 25 Jan 2018 13:31:03 -0700 Subject: [PATCH 7/7] changes from gchaps review --- docs/development/add-data-guide.asciidoc | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/development/add-data-guide.asciidoc b/docs/development/add-data-guide.asciidoc index 0e085954818d2..1b87087ce2931 100644 --- a/docs/development/add-data-guide.asciidoc +++ b/docs/development/add-data-guide.asciidoc @@ -1,20 +1,19 @@ [[add-data-guide]] -== Add Data guide +== Add Data Guide -`Add Data` in the Kibana Home application contains a collection of tutorials for setting up data flows in the Elastic stack. +`Add Data` in the Kibana Home application contains tutorials for setting up data flows in the Elastic stack. -Each tutorial contains 3 sets of instructions +Each tutorial contains three sets of instructions: -1. `On Premise` Instructions for setting up a data flow when both Kibana and Elasticsearch are running on premise -2. `On Premise Elastic Cloud` Instructions for setting up a data flow when Kibana is running on premise but -Elasticsearch is running on cloud. -3. `Elastic Cloud` Instructions for setting up a data flow when both Kibana and Elasticsearch are running on cloud. +* `On Premise.` Set up a data flow when both Kibana and Elasticsearch are running on premise. +* `On Premise Elastic Cloud.` Set up a data flow when Kibana is running on premise and Elasticsearch is running on Elastic Cloud. +* `Elastic Cloud.` Set up a data flow when both Kibana and Elasticsearch are running on Elastic Cloud. [float] === Creating a new tutorial 1. Create a new directory in the link:https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/server/tutorials[tutorials directory]. 2. In the new directory, create a file called `index.js` that exports a function. -The function must return a Javascript object that conforms to the link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/common/tutorials/tutorial_schema.js[tutorial schema]. +The function must return a JavaScript object that conforms to the link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/common/tutorials/tutorial_schema.js[tutorial schema]. 3. Register the tutorial in link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/server/tutorials/register.js[register.js] by calling `server.registerTutorial(myFuncImportedFromIndexJs)`. 4. Add image assets to the link:https://github.com/elastic/kibana/tree/master/src/core_plugins/kibana/public/home/tutorial_resources[tutorial_resources directory]. 5. Run Kibana locally to preview the tutorial. @@ -22,14 +21,14 @@ The function must return a Javascript object that conforms to the link:https://g [float] ==== Variables -String values can contain variables that get substituted when rendered. Variables are specified by `{}`. -For example: `{config.docs.version}` would get rendered as `6.2` when running the tutorial in Kibana 6.2. +String values can contain variables that are substituted when rendered. Variables are specified by `{}`. +For example: `{config.docs.version}` is rendered as `6.2` when running the tutorial in Kibana 6.2. link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/replace_template_strings.js#L23[Provided variables] [float] ==== Markdown -String values can contain limited markdown syntax. +String values can contain limited Markdown syntax. -link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/content.js#L8[Enabled markdown grammars] +link:https://github.com/elastic/kibana/blob/master/src/core_plugins/kibana/public/home/components/tutorial/content.js#L8[Enabled Markdown grammars]