alexeyinkin commented on code in PR #25507:
URL: https://github.com/apache/beam/pull/25507#discussion_r1112846542
##########
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
+```
+
+You will need it to embed the Playground code.
+
+### Source 2. Playground Unlisted Database
+
+If your snippet is less useful to public for learning but still beneficial to
some group
+of people, you can put it into the same database as the Playground Visible
Catalog
+but make it unlisted.
+
+Advantages:
+
+- 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.
+
+Proceed the same way as with Playground Visible Catalog, but do not use these
attributes:
+
+- `categories`
+- `default_example`
+- `tags`
+
+**TODO: How to get the path of the example?**
Review Comment:
How to get the ID of a snippet that does not show in the catalog after
merging its PR? @TSultanov
##########
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?**
Review Comment:
Is this complete and true? @TSultanov
##########
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:
1. Are these IDs of the same namespace as those of user-shared snippets? If
so, can we call pass any of them to any endpoints like `getSnippet()` for
`SDK_JAVA_MinimalWordCount`?
2. Since the ID is user-visible, how is it composed? Is it `"SDK_XXX" + "_"
+ <name_attribute_from_metadata>`?
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
