TSultanov commented on code in PR #25507:
URL: https://github.com/apache/beam/pull/25507#discussion_r1112961391
##########
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:
Full list can be seen
[here](https://github.com/apache/beam/blob/921bc7b94708391eb7d980cb8d9ed35c80d3aebb/playground/infrastructure/helper.py#L69)
and
[here](https://github.com/apache/beam/blob/921bc7b94708391eb7d980cb8d9ed35c80d3aebb/playground/infrastructure/models.py#L70).
So, missing attributes are:
- `pipeline_options` - options which will be passed to the pipeline
executor, e.g. `--output output.txt`
- `emulators` - list of emulators to start during pipeline execution.
Currently only `kafka` type is supported. Example:
```yaml
emulators:
- type: kafka
topic:
id: dataset
source_dataset: CountWords
```
- `datasets` - specify datasets which will be used by emulators, e.g.:
```yaml
datasets:
CountWords:
location: local
format: json
```
here name of dataset should be the name of the file with the data, possible
values of `format` are `avro` or `json` and `location` can be either `local` or
`GCS` (only `local` is supported by playground backend).
- `multifile` - indicates whether given example has additional files
associated with it
- `files` - list of files to include together with the example if
`multifile` is `true`
- `url_notebook` - ???? can't find usage
--
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]
