[CI] Support code-snippet extraction and docs-updating (open-telemetry#3948)

Author: chalin

.gitignore

@@ -26,3 +26,6 @@ assets/jsconfig.json
 
 # Webstorm
 /.idea/**
+
+.dart_tool
+pubspec.lock

.gitmodules

@@ -23,3 +23,7 @@
 	path = content-modules/opamp-spec
 	url = https://github.com/open-telemetry/opamp-spec
 	opamp-pin = v0.8.0-5-g0360da8
+[submodule "content-modules/opentelemetry-go"]
+	path = content-modules/opentelemetry-go
+	url = https://github.com/open-telemetry/opentelemetry-go
+  go-pin = v1.23.0-rc.1-31-geabcef4c2

content-modules/opentelemetry-go

@@ -5,6 +5,9 @@ weight: 10
 cSpell:ignore: chan fatalln funcs intn itoa khtml otelhttp rolldice stdouttrace strconv
 ---
 
+<!-- markdownlint-disable blanks-around-fences -->
+<?code-excerpt path-base="examples/go/dice"?>
+
 This page will show you how to get started with OpenTelemetry in Go.
 
 You will learn how you can instrument a simple application manually, in such a
@@ -121,6 +124,8 @@ application that exports telemetry.
 
 Create `otel.go` with OpenTelemetry SDK bootstrapping code:
 
+<!-- prettier-ignore-start -->
+<?code-excerpt "otel.go" from="package main"?>
 ```go
 package main
 
@@ -220,6 +225,7 @@ func newMeterProvider() (*metric.MeterProvider, error) {
 	return meterProvider, nil
 }
 ```
+<!-- prettier-ignore-end -->
 
 If you're only using tracing or metrics, you can omit the code the corresponding
 TracerProvider or MeterProvider initialization code.
@@ -232,6 +238,8 @@ server.
 Modify `main.go` to include code that sets up OpenTelemetry SDK and instruments
 the HTTP server using the `otelhttp` instrumentation library:
 
+<!-- prettier-ignore-start -->
+<?code-excerpt "main.go" from="package main"?>
 ```go
 package main
 
@@ -317,6 +325,7 @@ func newHTTPHandler() http.Handler {
 	return handler
 }
 ```
+<!-- prettier-ignore-end -->
 
 ### Add Custom Instrumentation
 
@@ -327,6 +336,8 @@ your application. For that you'll need to write some custom
 
 Modify `rolldice.go` to include custom instrumentation using OpenTelemetry API:
 
+<!-- prettier-ignore-start -->
+<?code-excerpt "rolldice.go" from="package main"?>
 ```go
 package main
 
@@ -364,7 +375,6 @@ func rolldice(w http.ResponseWriter, r *http.Request) {
 
 	roll := 1 + rand.Intn(6)
 
-	// Add the custom attribute to the span and counter.
 	rollValueAttr := attribute.Int("roll.value", roll)
 	span.SetAttributes(rollValueAttr)
 	rollCnt.Add(ctx, 1, metric.WithAttributes(rollValueAttr))
@@ -375,6 +385,7 @@ func rolldice(w http.ResponseWriter, r *http.Request) {
 	}
 }
 ```
+<!-- prettier-ignore-end -->
 
 Note that if you're only using tracing or metrics, you can omit the
 corresponding code that instruments the other telemetry type.

content/en/docs/languages/go/getting-started.md

@@ -0,0 +1,4 @@
+# Examples
+
+The files in this folder are used to extract code snippets that are used in the
+docs.

examples/README.md

@@ -0,0 +1 @@
+../content-modules/opentelemetry-go/example

examples/go

@@ -43,6 +43,9 @@
     "check:text": "npm run _check:text -- ",
     "check": "npm run seq -- $(npm run -s _list:check:*)",
     "clean": "make clean",
+    "code-excerpts": "rm -Rf tmp/excerpts/* && npm run seq -- code-excerpts:get code-excerpts:update-docs",
+    "code-excerpts:get": "cd tools && dart run build_runner build --delete-conflicting-outputs --output ../tmp/excerpts",
+    "code-excerpts:update-docs": "cd tools && dart run code_excerpt_updater --fragment-dir-path ../tmp/excerpts --src-dir-path examples --yaml --write-in-place content",
     "cp:spec": "./scripts/content-modules/cp-pages.sh",
     "diff:check": "npm run _diff:check || (echo; echo 'WARNING: the files above have not been committed'; echo)",
     "diff:fail": "npm run _diff:check || (echo; echo 'ERROR: the files above have changed. Locally rerun `npm run test-and-fix` and commit changes'; echo; exit 1)",

package.json

@@ -0,0 +1,11 @@
+# Tools for handling code excerpts
+
+This directory contains the tooling, config, and data sources for managing code
+excerpts. This functionality is currently experimental, and used only by site
+maintainers.
+
+## Dependencies
+
+- **Dart**: for installation instructions, see [Get the Dart SDK].
+
+[Get the Dart SDK]: https://dart.dev/get-dart

tools/README.md

@@ -0,0 +1,12 @@
+targets:
+  $default:
+    sources:
+      include:
+        - examples/**
+        # The following are included to avoid "required resources" tool warnings:
+        - $package$
+        - lib/$lib$
+      # exclude: ['**/.*/**']
+    builders:
+      code_excerpter|code_excerpter:
+        enabled: true

tools/build.yaml

@@ -0,0 +1 @@
+../../content/en/docs/languages/go

tools/content/go

@@ -0,0 +1 @@
+../examples

tools/examples

@@ -0,0 +1,16 @@
+name: otel_io_excerpts
+publish_to: none
+
+environment:
+  sdk: ^3.2.0
+
+dev_dependencies:
+  build_runner: ^2.4.6
+  code_excerpter:
+    git:
+      url: https://github.com/chalin/site-shared
+      path: packages/code_excerpter
+  code_excerpt_updater:
+    git:
+      url: https://github.com/chalin/site-shared
+      path: packages/code_excerpt_updater