You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@beam.apache.org by "TSultanov (via GitHub)" <gi...@apache.org> on 2023/02/20 09:00:23 UTC
[GitHub] [beam] TSultanov commented on a diff in pull request #25507: Overview of adding snippets to Playground (#25506)
TSultanov commented on code in PR #25507:
URL: https://github.com/apache/beam/pull/25507#discussion_r1111641317
##########
playground/get_your_code.md:
##########
@@ -0,0 +1,449 @@
+# How to Get Your Code into Apache Beam Playground
+
+Getting your code into the Playground is a three-step process:
+
+1. Prepare your code.
+2. Place your code somewhere the Playground can load it from.
+3. Create a link to view it or a code to embed.
+
+For the last two steps there are multiple options -- pick any source and use any embedding:
+
+
+
+They can be combined, e.g.
+"put the code to the Playground catalog, embed the Playground to any HTML", or
+"upload the code to any website, embed the Playground to Apache Beam docs with Markdown".
+
+# Table of Contents
+- [Step 1. Prepare Your Code](#step-1-prepare-your-code)
+ * [Named Sections](#named-sections)
+- [Step 2. Place your code somewhere the Playground can load it from](#step-2-place-your-code-somewhere-the-playground-can-load-it-from)
+ * [Source 1. Playground Visible Catalog](#source-1-playground-visible-catalog)
+ + [1. Put the file to the directory](#1-put-the-file-to-the-directory)
+ + [2. Add metadata](#2-add-metadata)
+ + [3. Make a PR](#3-make-a-pr)
+ + [4. Save the snippet path](#4-save-the-snippet-path)
+ * [Source 2. Playground Unlisted Database](#source-2-playground-unlisted-database)
+ * [Source 3. Tour of Beam unit](#source-3-tour-of-beam-unit)
+ * [Source 4. User-shared Code](#source-4-user-shared-code)
+ * [Source 5. HTTPS](#source-5-https)
+- [Step 3. Create a link or embed](#step-3-create-a-link-or-embed)
+ * [Direct Link to the Standalone Playground Web App](#direct-link-to-the-standalone-playground-web-app)
+ + [1. Link for a snippet from Playground Visible Catalog](#1-link-for-a-snippet-from-playground-visible-catalog)
+ + [2. Link for a snippet from Playground Unlisted Database](#2-link-for-a-snippet-from-playground-unlisted-database)
+ + [3. Link for a Tour of Beam Unit](#3-link-for-a-tour-of-beam-unit)
+ + [4. Link for User-shared Code](#4-link-for-user-shared-code)
+ + [5. Link for an HTTPS-served snippet](#5-link-for-an-https-served-snippet)
+ + [6. Link to an empty editor](#6-link-to-an-empty-editor)
+ + [Passing View Options](#passing-view-options)
+ - [Read-only sections](#read-only-sections)
+ - [Folding everything except sections](#folding-everything-except-sections)
+ - [Hiding everything except a section](#hiding-everything-except-a-section)
+ + [Linking to multiple examples](#linking-to-multiple-examples)
+ + [Embedded vs Standalone Playground URLs](#embedded-vs-standalone-playground-urls)
+ * [Embed into HTML](#embed-into-html)
+ + [1. Embed a snippet from Playground Visible Catalog](#1-embed-a-snippet-from-playground-visible-catalog)
+ + [2. Embed User-shared Code](#2-embed-user-shared-code)
+ + [3. Embed a snippet from any other source](#3-embed-a-snippet-from-any-other-source)
+ * [Embedding into the Beam documentation](#embedding-into-the-beam-documentation)
+
+
+## Step 1. Prepare Your Code
+
+Playground has multiple features to focus users to certain parts of the code.
+It does the following to all snippets:
+
+- Folds a comment if a snippet starts with one.
+- Folds imports.
+
+Additionally it can apply the following view options:
+
+- Fold all blocks except certain ones.
+- Completely hide all code except certain parts.
+- Make certain parts read-only.
+
+If you do not need any of those view options, skip to the [next step](#step-2-place-your-code-somewhere-the-playground-can-load-it-from).
+
+### Named Sections
+
+For those features to work, the snippet must contain sections with the following syntax:
+
+```
+// [START section_name]
+void method() {
+...
+}
+// [END section_name]
+```
+
+See more on the syntax and limitations in the
+[README of the editor](https://pub.dev/packages/flutter_code_editor)
+that Playground uses.
+
+Create a named section for each part of your code that you want that features for.
+
+## Step 2. Place your code somewhere the Playground can load it from
+
+### Source 1. Playground Visible Catalog
+
+If you think your snippet is beneficial to many users, it's a good idea to add it to
+the Playground Catalog.
+
+Advantages:
+
+- Anyone can find your snippet in the dropdown when they open Playground.
+- The CI of the Beam repository guarantees your snippet builds and runs correctly.
+- Output and graph are cached so the viewers of your snippet will not wait when they run it.
+
+#### 1. Put the file to the directory
+
+Snippets for the Playground Catalog are automatically picked from predefined categories
+by a workflow **(WHICH ONE?)** after merging a PR.
+
+This directories are:
+
+| SDK | Snippet path root |
+|-|-|
+| Java | **?** |
+| Python | **?** |
+| Go | **?** |
Review Comment:
`/learning/katas`, `/examples` and `/sdks` for all three SDKs,files with examples are chosen based on filename extension
##########
playground/get_your_code.md:
##########
@@ -0,0 +1,449 @@
+# How to Get Your Code into Apache Beam Playground
+
+Getting your code into the Playground is a three-step process:
+
+1. Prepare your code.
+2. Place your code somewhere the Playground can load it from.
+3. Create a link to view it or a code to embed.
+
+For the last two steps there are multiple options -- pick any source and use any embedding:
+
+
+
+They can be combined, e.g.
+"put the code to the Playground catalog, embed the Playground to any HTML", or
+"upload the code to any website, embed the Playground to Apache Beam docs with Markdown".
+
+# Table of Contents
+- [Step 1. Prepare Your Code](#step-1-prepare-your-code)
+ * [Named Sections](#named-sections)
+- [Step 2. Place your code somewhere the Playground can load it from](#step-2-place-your-code-somewhere-the-playground-can-load-it-from)
+ * [Source 1. Playground Visible Catalog](#source-1-playground-visible-catalog)
+ + [1. Put the file to the directory](#1-put-the-file-to-the-directory)
+ + [2. Add metadata](#2-add-metadata)
+ + [3. Make a PR](#3-make-a-pr)
+ + [4. Save the snippet path](#4-save-the-snippet-path)
+ * [Source 2. Playground Unlisted Database](#source-2-playground-unlisted-database)
+ * [Source 3. Tour of Beam unit](#source-3-tour-of-beam-unit)
+ * [Source 4. User-shared Code](#source-4-user-shared-code)
+ * [Source 5. HTTPS](#source-5-https)
+- [Step 3. Create a link or embed](#step-3-create-a-link-or-embed)
+ * [Direct Link to the Standalone Playground Web App](#direct-link-to-the-standalone-playground-web-app)
+ + [1. Link for a snippet from Playground Visible Catalog](#1-link-for-a-snippet-from-playground-visible-catalog)
+ + [2. Link for a snippet from Playground Unlisted Database](#2-link-for-a-snippet-from-playground-unlisted-database)
+ + [3. Link for a Tour of Beam Unit](#3-link-for-a-tour-of-beam-unit)
+ + [4. Link for User-shared Code](#4-link-for-user-shared-code)
+ + [5. Link for an HTTPS-served snippet](#5-link-for-an-https-served-snippet)
+ + [6. Link to an empty editor](#6-link-to-an-empty-editor)
+ + [Passing View Options](#passing-view-options)
+ - [Read-only sections](#read-only-sections)
+ - [Folding everything except sections](#folding-everything-except-sections)
+ - [Hiding everything except a section](#hiding-everything-except-a-section)
+ + [Linking to multiple examples](#linking-to-multiple-examples)
+ + [Embedded vs Standalone Playground URLs](#embedded-vs-standalone-playground-urls)
+ * [Embed into HTML](#embed-into-html)
+ + [1. Embed a snippet from Playground Visible Catalog](#1-embed-a-snippet-from-playground-visible-catalog)
+ + [2. Embed User-shared Code](#2-embed-user-shared-code)
+ + [3. Embed a snippet from any other source](#3-embed-a-snippet-from-any-other-source)
+ * [Embedding into the Beam documentation](#embedding-into-the-beam-documentation)
+
+
+## Step 1. Prepare Your Code
+
+Playground has multiple features to focus users to certain parts of the code.
+It does the following to all snippets:
+
+- Folds a comment if a snippet starts with one.
+- Folds imports.
+
+Additionally it can apply the following view options:
+
+- Fold all blocks except certain ones.
+- Completely hide all code except certain parts.
+- Make certain parts read-only.
+
+If you do not need any of those view options, skip to the [next step](#step-2-place-your-code-somewhere-the-playground-can-load-it-from).
+
+### Named Sections
+
+For those features to work, the snippet must contain sections with the following syntax:
+
+```
+// [START section_name]
+void method() {
+...
+}
+// [END section_name]
+```
+
+See more on the syntax and limitations in the
+[README of the editor](https://pub.dev/packages/flutter_code_editor)
+that Playground uses.
+
+Create a named section for each part of your code that you want that features for.
+
+## Step 2. Place your code somewhere the Playground can load it from
+
+### Source 1. Playground Visible Catalog
+
+If you think your snippet is beneficial to many users, it's a good idea to add it to
+the Playground Catalog.
+
+Advantages:
+
+- Anyone can find your snippet in the dropdown when they open Playground.
+- The CI of the Beam repository guarantees your snippet builds and runs correctly.
+- Output and graph are cached so the viewers of your snippet will not wait when they run it.
+
+#### 1. Put the file to the directory
+
+Snippets for the Playground Catalog are automatically picked from predefined categories
+by a workflow **(WHICH ONE?)** after merging a PR.
+
+This directories are:
+
+| SDK | Snippet path root |
+|-|-|
+| Java | **?** |
+| Python | **?** |
+| Go | **?** |
+
+Place the file anywhere under the given directory.
+
+**TODO: NAMING, DIRECTORY STRUCTURE?**
+
+Snippets in Scala are not yet supported for by that workflow.
+All existing Scala examples are added manually by the team.
+Please use other options to place your Scala snippets.
+
+#### 2. Add metadata
+
+Playground needs metadata to put a snippet to the database. These are stored as a comment block
+anywhere in the snippet.
+See [this](https://github.com/apache/beam/blob/3e080ff212d8ed7208c8486b515bb73c5d294475/examples/java/src/main/java/org/apache/beam/examples/MinimalWordCount.java#L20-L36) for an example.
+This comment block is cut from the text before putting it to the database and so is not visible
+to end users. The block is in the format of a YAML map.
+
+The following attributes are required:
+
+| Attribute | Description | Values |
+|-|-|-|
+| `description` | Description text to show on mouse over. | Text | Required |
+| `multifile` | Whether this is a file of a multi-file example. | `true`, `false` | Required |
+| `name` | Name to show in the dropdown. | Text| Required |
+
+The following optional attributes are supported:
+
+| Attribute | Description | Values |
+|-|-|-|
+| `categories` | Titles of categories to list this snippet in. Non-existent categories will be created. | Array of strings |
+| `complexity` | How hard is the snippet to understand. | `BASIC`, `MEDIUM`, `ADVANCED` |
+| `context_line` | The line number to scroll to when the snippet is loaded. This applies after the metadata block is removed from the file, so discount for those lines. | Integer, 1-based |
+| `default_example` | Whether this is the default example in its SDK. If multiple snippets set this to `true` the behavior is undefined. | `false` (default), `true` |
+| `tags` | Tags by which this snippet can be found in the dropdown. | Array of strings |
+
+**TODO: ARE THE REQUIRED AND OPTIONAL ATTRIBUTES IDENTIFIED CORRECTLY?**
+
+**TODO: ARE THERE ANY OTHER SUPPORTED ATTRIBUTES?**
+
+#### 3. Make a PR
+
+Make a PR into [the Beam repository](https://github.com/apache/beam).
+Make sure all checks are green.
+
+A reviewer will be assigned. After merge the snippet will be visible in the Playground dropdown.
+
+The CI we have will also check that the example compiles and runs alright.
+
+#### 4. Save the snippet path
+
+The snippet will be assigned a path to identify it.
+You can find it in the address bar of the browser when you select it in the dropdown.
+
+For example, this URL:
+
+```
+https://play.beam.apache.org/?path=SDK_JAVA%2FPRECOMPILED_OBJECT_TYPE_EXAMPLE%2FMinimalWordCount&sdk=java
Review Comment:
We use IDs now instead of paths, like `SDK_JAVA_MinimalWordCount`
##########
playground/get_your_code.md:
##########
@@ -0,0 +1,449 @@
+# How to Get Your Code into Apache Beam Playground
+
+Getting your code into the Playground is a three-step process:
+
+1. Prepare your code.
+2. Place your code somewhere the Playground can load it from.
+3. Create a link to view it or a code to embed.
+
+For the last two steps there are multiple options -- pick any source and use any embedding:
+
+
+
+They can be combined, e.g.
+"put the code to the Playground catalog, embed the Playground to any HTML", or
+"upload the code to any website, embed the Playground to Apache Beam docs with Markdown".
+
+# Table of Contents
+- [Step 1. Prepare Your Code](#step-1-prepare-your-code)
+ * [Named Sections](#named-sections)
+- [Step 2. Place your code somewhere the Playground can load it from](#step-2-place-your-code-somewhere-the-playground-can-load-it-from)
+ * [Source 1. Playground Visible Catalog](#source-1-playground-visible-catalog)
+ + [1. Put the file to the directory](#1-put-the-file-to-the-directory)
+ + [2. Add metadata](#2-add-metadata)
+ + [3. Make a PR](#3-make-a-pr)
+ + [4. Save the snippet path](#4-save-the-snippet-path)
+ * [Source 2. Playground Unlisted Database](#source-2-playground-unlisted-database)
+ * [Source 3. Tour of Beam unit](#source-3-tour-of-beam-unit)
+ * [Source 4. User-shared Code](#source-4-user-shared-code)
+ * [Source 5. HTTPS](#source-5-https)
+- [Step 3. Create a link or embed](#step-3-create-a-link-or-embed)
+ * [Direct Link to the Standalone Playground Web App](#direct-link-to-the-standalone-playground-web-app)
+ + [1. Link for a snippet from Playground Visible Catalog](#1-link-for-a-snippet-from-playground-visible-catalog)
+ + [2. Link for a snippet from Playground Unlisted Database](#2-link-for-a-snippet-from-playground-unlisted-database)
+ + [3. Link for a Tour of Beam Unit](#3-link-for-a-tour-of-beam-unit)
+ + [4. Link for User-shared Code](#4-link-for-user-shared-code)
+ + [5. Link for an HTTPS-served snippet](#5-link-for-an-https-served-snippet)
+ + [6. Link to an empty editor](#6-link-to-an-empty-editor)
+ + [Passing View Options](#passing-view-options)
+ - [Read-only sections](#read-only-sections)
+ - [Folding everything except sections](#folding-everything-except-sections)
+ - [Hiding everything except a section](#hiding-everything-except-a-section)
+ + [Linking to multiple examples](#linking-to-multiple-examples)
+ + [Embedded vs Standalone Playground URLs](#embedded-vs-standalone-playground-urls)
+ * [Embed into HTML](#embed-into-html)
+ + [1. Embed a snippet from Playground Visible Catalog](#1-embed-a-snippet-from-playground-visible-catalog)
+ + [2. Embed User-shared Code](#2-embed-user-shared-code)
+ + [3. Embed a snippet from any other source](#3-embed-a-snippet-from-any-other-source)
+ * [Embedding into the Beam documentation](#embedding-into-the-beam-documentation)
+
+
+## Step 1. Prepare Your Code
+
+Playground has multiple features to focus users to certain parts of the code.
+It does the following to all snippets:
+
+- Folds a comment if a snippet starts with one.
+- Folds imports.
+
+Additionally it can apply the following view options:
+
+- Fold all blocks except certain ones.
+- Completely hide all code except certain parts.
+- Make certain parts read-only.
+
+If you do not need any of those view options, skip to the [next step](#step-2-place-your-code-somewhere-the-playground-can-load-it-from).
+
+### Named Sections
+
+For those features to work, the snippet must contain sections with the following syntax:
+
+```
+// [START section_name]
+void method() {
+...
+}
+// [END section_name]
+```
+
+See more on the syntax and limitations in the
+[README of the editor](https://pub.dev/packages/flutter_code_editor)
+that Playground uses.
+
+Create a named section for each part of your code that you want that features for.
+
+## Step 2. Place your code somewhere the Playground can load it from
+
+### Source 1. Playground Visible Catalog
+
+If you think your snippet is beneficial to many users, it's a good idea to add it to
+the Playground Catalog.
+
+Advantages:
+
+- Anyone can find your snippet in the dropdown when they open Playground.
+- The CI of the Beam repository guarantees your snippet builds and runs correctly.
+- Output and graph are cached so the viewers of your snippet will not wait when they run it.
+
+#### 1. Put the file to the directory
+
+Snippets for the Playground Catalog are automatically picked from predefined categories
+by a workflow **(WHICH ONE?)** after merging a PR.
+
+This directories are:
+
+| SDK | Snippet path root |
+|-|-|
+| Java | **?** |
+| Python | **?** |
+| Go | **?** |
+
+Place the file anywhere under the given directory.
+
+**TODO: NAMING, DIRECTORY STRUCTURE?**
+
+Snippets in Scala are not yet supported for by that workflow.
+All existing Scala examples are added manually by the team.
+Please use other options to place your Scala snippets.
+
+#### 2. Add metadata
+
+Playground needs metadata to put a snippet to the database. These are stored as a comment block
+anywhere in the snippet.
+See [this](https://github.com/apache/beam/blob/3e080ff212d8ed7208c8486b515bb73c5d294475/examples/java/src/main/java/org/apache/beam/examples/MinimalWordCount.java#L20-L36) for an example.
+This comment block is cut from the text before putting it to the database and so is not visible
+to end users. The block is in the format of a YAML map.
+
+The following attributes are required:
+
+| Attribute | Description | Values |
+|-|-|-|
+| `description` | Description text to show on mouse over. | Text | Required |
+| `multifile` | Whether this is a file of a multi-file example. | `true`, `false` | Required |
+| `name` | Name to show in the dropdown. | Text| Required |
+
+The following optional attributes are supported:
+
+| Attribute | Description | Values |
+|-|-|-|
+| `categories` | Titles of categories to list this snippet in. Non-existent categories will be created. | Array of strings |
+| `complexity` | How hard is the snippet to understand. | `BASIC`, `MEDIUM`, `ADVANCED` |
+| `context_line` | The line number to scroll to when the snippet is loaded. This applies after the metadata block is removed from the file, so discount for those lines. | Integer, 1-based |
+| `default_example` | Whether this is the default example in its SDK. If multiple snippets set this to `true` the behavior is undefined. | `false` (default), `true` |
+| `tags` | Tags by which this snippet can be found in the dropdown. | Array of strings |
+
+**TODO: ARE THE REQUIRED AND OPTIONAL ATTRIBUTES IDENTIFIED CORRECTLY?**
+
+**TODO: ARE THERE ANY OTHER SUPPORTED ATTRIBUTES?**
+
+#### 3. Make a PR
+
+Make a PR into [the Beam repository](https://github.com/apache/beam).
+Make sure all checks are green.
+
+A reviewer will be assigned. After merge the snippet will be visible in the Playground dropdown.
+
+The CI we have will also check that the example compiles and runs alright.
+
+#### 4. Save the snippet path
+
+The snippet will be assigned a path to identify it.
+You can find it in the address bar of the browser when you select it in the dropdown.
+
+For example, this URL:
+
+```
+https://play.beam.apache.org/?path=SDK_JAVA%2FPRECOMPILED_OBJECT_TYPE_EXAMPLE%2FMinimalWordCount&sdk=java
+```
+
+after [URL decoding](https://www.urldecoder.org) indicates this snippet path:
+
+```
+SDK_JAVA/PRECOMPILED_OBJECT_TYPE_EXAMPLE/MinimalWordCount
Review Comment:
`SDK_JAVA_MinimalWordCount`
##########
playground/get_your_code.md:
##########
@@ -0,0 +1,449 @@
+# How to Get Your Code into Apache Beam Playground
+
+Getting your code into the Playground is a three-step process:
+
+1. Prepare your code.
+2. Place your code somewhere the Playground can load it from.
+3. Create a link to view it or a code to embed.
+
+For the last two steps there are multiple options -- pick any source and use any embedding:
+
+
+
+They can be combined, e.g.
+"put the code to the Playground catalog, embed the Playground to any HTML", or
+"upload the code to any website, embed the Playground to Apache Beam docs with Markdown".
+
+# Table of Contents
+- [Step 1. Prepare Your Code](#step-1-prepare-your-code)
+ * [Named Sections](#named-sections)
+- [Step 2. Place your code somewhere the Playground can load it from](#step-2-place-your-code-somewhere-the-playground-can-load-it-from)
+ * [Source 1. Playground Visible Catalog](#source-1-playground-visible-catalog)
+ + [1. Put the file to the directory](#1-put-the-file-to-the-directory)
+ + [2. Add metadata](#2-add-metadata)
+ + [3. Make a PR](#3-make-a-pr)
+ + [4. Save the snippet path](#4-save-the-snippet-path)
+ * [Source 2. Playground Unlisted Database](#source-2-playground-unlisted-database)
+ * [Source 3. Tour of Beam unit](#source-3-tour-of-beam-unit)
+ * [Source 4. User-shared Code](#source-4-user-shared-code)
+ * [Source 5. HTTPS](#source-5-https)
+- [Step 3. Create a link or embed](#step-3-create-a-link-or-embed)
+ * [Direct Link to the Standalone Playground Web App](#direct-link-to-the-standalone-playground-web-app)
+ + [1. Link for a snippet from Playground Visible Catalog](#1-link-for-a-snippet-from-playground-visible-catalog)
+ + [2. Link for a snippet from Playground Unlisted Database](#2-link-for-a-snippet-from-playground-unlisted-database)
+ + [3. Link for a Tour of Beam Unit](#3-link-for-a-tour-of-beam-unit)
+ + [4. Link for User-shared Code](#4-link-for-user-shared-code)
+ + [5. Link for an HTTPS-served snippet](#5-link-for-an-https-served-snippet)
+ + [6. Link to an empty editor](#6-link-to-an-empty-editor)
+ + [Passing View Options](#passing-view-options)
+ - [Read-only sections](#read-only-sections)
+ - [Folding everything except sections](#folding-everything-except-sections)
+ - [Hiding everything except a section](#hiding-everything-except-a-section)
+ + [Linking to multiple examples](#linking-to-multiple-examples)
+ + [Embedded vs Standalone Playground URLs](#embedded-vs-standalone-playground-urls)
+ * [Embed into HTML](#embed-into-html)
+ + [1. Embed a snippet from Playground Visible Catalog](#1-embed-a-snippet-from-playground-visible-catalog)
+ + [2. Embed User-shared Code](#2-embed-user-shared-code)
+ + [3. Embed a snippet from any other source](#3-embed-a-snippet-from-any-other-source)
+ * [Embedding into the Beam documentation](#embedding-into-the-beam-documentation)
+
+
+## Step 1. Prepare Your Code
+
+Playground has multiple features to focus users to certain parts of the code.
+It does the following to all snippets:
+
+- Folds a comment if a snippet starts with one.
+- Folds imports.
+
+Additionally it can apply the following view options:
+
+- Fold all blocks except certain ones.
+- Completely hide all code except certain parts.
+- Make certain parts read-only.
+
+If you do not need any of those view options, skip to the [next step](#step-2-place-your-code-somewhere-the-playground-can-load-it-from).
+
+### Named Sections
+
+For those features to work, the snippet must contain sections with the following syntax:
+
+```
+// [START section_name]
+void method() {
+...
+}
+// [END section_name]
+```
+
+See more on the syntax and limitations in the
+[README of the editor](https://pub.dev/packages/flutter_code_editor)
+that Playground uses.
+
+Create a named section for each part of your code that you want that features for.
+
+## Step 2. Place your code somewhere the Playground can load it from
+
+### Source 1. Playground Visible Catalog
+
+If you think your snippet is beneficial to many users, it's a good idea to add it to
+the Playground Catalog.
+
+Advantages:
+
+- Anyone can find your snippet in the dropdown when they open Playground.
+- The CI of the Beam repository guarantees your snippet builds and runs correctly.
+- Output and graph are cached so the viewers of your snippet will not wait when they run it.
+
+#### 1. Put the file to the directory
+
+Snippets for the Playground Catalog are automatically picked from predefined categories
+by a workflow **(WHICH ONE?)** after merging a PR.
+
+This directories are:
+
+| SDK | Snippet path root |
+|-|-|
+| Java | **?** |
+| Python | **?** |
+| Go | **?** |
Review Comment:
and `/learning/tour-of-beam/learning-content" for Tour of Beam
##########
playground/get_your_code.md:
##########
@@ -0,0 +1,449 @@
+# How to Get Your Code into Apache Beam Playground
+
+Getting your code into the Playground is a three-step process:
+
+1. Prepare your code.
+2. Place your code somewhere the Playground can load it from.
+3. Create a link to view it or a code to embed.
+
+For the last two steps there are multiple options -- pick any source and use any embedding:
+
+
+
+They can be combined, e.g.
+"put the code to the Playground catalog, embed the Playground to any HTML", or
+"upload the code to any website, embed the Playground to Apache Beam docs with Markdown".
+
+# Table of Contents
+- [Step 1. Prepare Your Code](#step-1-prepare-your-code)
+ * [Named Sections](#named-sections)
+- [Step 2. Place your code somewhere the Playground can load it from](#step-2-place-your-code-somewhere-the-playground-can-load-it-from)
+ * [Source 1. Playground Visible Catalog](#source-1-playground-visible-catalog)
+ + [1. Put the file to the directory](#1-put-the-file-to-the-directory)
+ + [2. Add metadata](#2-add-metadata)
+ + [3. Make a PR](#3-make-a-pr)
+ + [4. Save the snippet path](#4-save-the-snippet-path)
+ * [Source 2. Playground Unlisted Database](#source-2-playground-unlisted-database)
+ * [Source 3. Tour of Beam unit](#source-3-tour-of-beam-unit)
+ * [Source 4. User-shared Code](#source-4-user-shared-code)
+ * [Source 5. HTTPS](#source-5-https)
+- [Step 3. Create a link or embed](#step-3-create-a-link-or-embed)
+ * [Direct Link to the Standalone Playground Web App](#direct-link-to-the-standalone-playground-web-app)
+ + [1. Link for a snippet from Playground Visible Catalog](#1-link-for-a-snippet-from-playground-visible-catalog)
+ + [2. Link for a snippet from Playground Unlisted Database](#2-link-for-a-snippet-from-playground-unlisted-database)
+ + [3. Link for a Tour of Beam Unit](#3-link-for-a-tour-of-beam-unit)
+ + [4. Link for User-shared Code](#4-link-for-user-shared-code)
+ + [5. Link for an HTTPS-served snippet](#5-link-for-an-https-served-snippet)
+ + [6. Link to an empty editor](#6-link-to-an-empty-editor)
+ + [Passing View Options](#passing-view-options)
+ - [Read-only sections](#read-only-sections)
+ - [Folding everything except sections](#folding-everything-except-sections)
+ - [Hiding everything except a section](#hiding-everything-except-a-section)
+ + [Linking to multiple examples](#linking-to-multiple-examples)
+ + [Embedded vs Standalone Playground URLs](#embedded-vs-standalone-playground-urls)
+ * [Embed into HTML](#embed-into-html)
+ + [1. Embed a snippet from Playground Visible Catalog](#1-embed-a-snippet-from-playground-visible-catalog)
+ + [2. Embed User-shared Code](#2-embed-user-shared-code)
+ + [3. Embed a snippet from any other source](#3-embed-a-snippet-from-any-other-source)
+ * [Embedding into the Beam documentation](#embedding-into-the-beam-documentation)
+
+
+## Step 1. Prepare Your Code
+
+Playground has multiple features to focus users to certain parts of the code.
+It does the following to all snippets:
+
+- Folds a comment if a snippet starts with one.
+- Folds imports.
+
+Additionally it can apply the following view options:
+
+- Fold all blocks except certain ones.
+- Completely hide all code except certain parts.
+- Make certain parts read-only.
+
+If you do not need any of those view options, skip to the [next step](#step-2-place-your-code-somewhere-the-playground-can-load-it-from).
+
+### Named Sections
+
+For those features to work, the snippet must contain sections with the following syntax:
+
+```
+// [START section_name]
+void method() {
+...
+}
+// [END section_name]
+```
+
+See more on the syntax and limitations in the
+[README of the editor](https://pub.dev/packages/flutter_code_editor)
+that Playground uses.
+
+Create a named section for each part of your code that you want that features for.
+
+## Step 2. Place your code somewhere the Playground can load it from
+
+### Source 1. Playground Visible Catalog
+
+If you think your snippet is beneficial to many users, it's a good idea to add it to
+the Playground Catalog.
+
+Advantages:
+
+- Anyone can find your snippet in the dropdown when they open Playground.
+- The CI of the Beam repository guarantees your snippet builds and runs correctly.
+- Output and graph are cached so the viewers of your snippet will not wait when they run it.
+
+#### 1. Put the file to the directory
+
+Snippets for the Playground Catalog are automatically picked from predefined categories
+by a workflow **(WHICH ONE?)** after merging a PR.
Review Comment:
`tour_of_beam_examples_ci.yml` for Tour of Beam, `playground_examples_ci.yml` for Playground
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@beam.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org