docs: generate documentation for integrations in dd-trace-go (#510)

Restores the documentation generation facility, sourcing integrations
from the `gopkg.in/DataDog/dd-trace-go.v1` package instead of the (now
removed) `builtin` package.

_docs/generator/doc.advice.add-blank-import.tmpl

@@ -0,0 +1,4 @@
+<span class="advice add-blank-import">
+  <span class="type">Add blank import of </span>
+  {{ "{{" }}<godoc import-path="{{ . }}">{{ "}}" }}
+</span>

_docs/generator/doc.advice.add-struct-field.tmpl

@@ -0,0 +1,4 @@
+<div class="advice add-struct-field">
+  <span class="type">Add new field</span>
+  <code>{{ .Name }}</code> of type {{ render .TypeName }}.
+</div>

_docs/generator/doc.advice.append-args.tmpl

@@ -0,0 +1,12 @@
+<div class="advice append-arguments">
+  <div class="type">
+    Append the following {{ render .TypeName }} arguments to the function call:
+  </div>
+  <ol>
+    {{- range .Templates }}
+    <li>
+      {{- "\n" }}{{ render . -}}
+    </li>
+    {{- end }}
+  </ol>
+</div>

_docs/generator/doc.advice.assign-value.tmpl

@@ -0,0 +1,4 @@
+<div class="advice assign-value">
+  <div class="type">Set initial value to:</div>
+  {{- "\n" }}{{ render .Template -}}
+</div>

_docs/generator/doc.advice.inject-declarations.tmpl

@@ -0,0 +1,12 @@
+<div class="advice inject-declarations">
+  <div class="type">Introduce new declarations:</div>
+  {{- "\n" }}{{ render .Template }}
+  {{- with .Links -}}
+  <div class="type">Record link-time dependencies on:</div>
+  <ul>
+    {{- range . }}
+    <li>{{ "{{" }}<godoc import-path="{{ . }}">{{ "}}" }}</li>
+    {{- end -}}
+  </ul>
+  {{- end }}
+</div>

_docs/generator/doc.advice.prepend-statements.tmpl

@@ -0,0 +1,4 @@
+<div class="advice prepend-statements">
+  <div class="type">Prepend statements produced by the following template:</div>
+  {{- "\n" }}{{ render .Template }}
+</div>

_docs/generator/doc.advice.redirect-call.tmpl

@@ -0,0 +1,5 @@
+<div class="advice redirect-call">
+  <div class="type">
+    Redirect the call to {{ "{{" }}<godoc import-path="{{ .ImportPath }}" name="{{ .Name }}">{{ "}}" }}.
+  </div>
+</div>

_docs/generator/doc.advice.wrap-expression.tmpl

@@ -0,0 +1,4 @@
+<div class="advice wrap-expression">
+  <div class="type">Replace the expression using the template:</div>
+  {{- "\n" }}{{ render .Template -}}
+</div>

_docs/generator/doc.code.template.tmpl

@@ -0,0 +1,14 @@
+{{- with .Imports }}
+```go
+// Using the following synthetic imports:
+import (
+{{- range $key, $value := . }}
+{{ "\t" }}{{ $key }} "{{ $value }}"
+{{- end }}
+)
+```
+{{- end }}
+
+```go-template
+{{ .Source | tabIndent | safe }}
+```

_docs/generator/doc.join.all-of.tmpl

@@ -0,0 +1,10 @@
+<div class="join-point all-of">
+  <span class="type pill">All of</span>
+  <ul>
+  {{- range . }}
+    <li class="candidate">
+      {{- render . -}}
+    </li>
+  {{- end }}
+  </ul>
+</div>

_docs/generator/doc.join.configuration.tmpl

@@ -0,0 +1,11 @@
+<div class="join-point configuration">
+  <span class="type pill">Configuration</span>
+  <ul>{{ range $key, $value := . }}
+    <li class="flex">
+      <span class="type">{{ $key }}</span>
+      <code>
+        {{ $value }}
+      </code>
+    </li>
+  {{ end }}</ul>
+</div>

_docs/generator/doc.join.directive.tmpl

@@ -0,0 +1,4 @@
+<div class="flex join-point directive">
+  <span class="type">Has directive</span>
+  <code>//{{- . }}</code>
+</div>

_docs/generator/doc.join.function-body.tmpl

@@ -0,0 +1,6 @@
+<div class="join-point function-body">
+  <span class="type pill">Function body</span>
+  <ul>
+    <li>{{ render .Function }}</li>
+  </ul>
+</div>

_docs/generator/doc.join.function-call.tmpl

@@ -0,0 +1,6 @@
+<div class="flex join-point function-call">
+  <span class="type">Call to</span>
+  {{ "{{" -}}
+  <godoc import-path="{{ .ImportPath }}" package="{{ packageName .ImportPath }}" name="{{ .Name }}">
+  {{- "}}" }}
+</div>

_docs/generator/doc.join.function-declaration.tmpl

@@ -0,0 +1,8 @@
+<div class="join-point function-declaration">
+  <span class="type pill">Function declaration</span>
+  <ul>
+  {{- range .Options }}
+    <li>{{- render . -}}</li>
+  {{- end }}
+  </ul>
+</div>

_docs/generator/doc.join.function-name.tmpl

@@ -0,0 +1,8 @@
+<div class="join-point {{ with . }}flex {{ end -}} function-option fo-name">
+  {{ with . -}}
+  <span class="type">Function name</span>
+  <code>{{ . }}</code>
+  {{- else -}}
+  <span class="type pill">Function literal expression</span>
+  {{- end }}
+</div>

_docs/generator/doc.join.import-path.tmpl

@@ -0,0 +1,6 @@
+<div class="flex join-point import-path">
+  <span class="type">Import path</span>
+  {{ "{{" -}}
+    <godoc import-path="{{ . }}">
+  {{- "}}" }}
+</div>

_docs/generator/doc.join.not.tmpl

@@ -0,0 +1,6 @@
+<div class="join-point not">
+  <span class="type pill">Not</span>
+  <ul>
+    <li>{{ render .JoinPoint }}</li>
+  </ul>
+</div>

_docs/generator/doc.join.one-of.tmpl

@@ -0,0 +1,10 @@
+<div class="join-point one-of">
+  <span class="type pill">One of</span>
+  <ul>
+  {{- range . -}}
+    <li class="candidate">
+      {{- render . -}}
+    </li>
+  {{- end -}}
+  </li>
+</div>

_docs/generator/doc.join.package-name.tmpl

@@ -0,0 +1,4 @@
+<div class="flex join-point package-name">
+  <span class="type">Package name</span>
+  <code>{{ . }}</code>
+</div>

_docs/generator/doc.join.receiver.tmpl

@@ -0,0 +1,4 @@
+<div class="flex join-point function-option fo-receiver">
+  <span class="type">Is method of</span>
+  {{ render .TypeName }}
+</div>

_docs/generator/doc.join.signature.tmpl

@@ -0,0 +1,42 @@
+<div class="join-point function-option fo-signature">
+  <span class="type pill">Signature matches</span>
+  <ul>
+    {{- with .Arguments }}
+    <li>
+      <span class="type pill">Arguments</span>
+      <ol>
+      {{- range . }}
+        <li class="flex">
+          <span class="id"></span>
+          {{ render . -}}
+        </li>
+      {{- end -}}
+      </ol>
+    </li>
+    {{- else -}}
+    <li class="flex">
+      <span class="type">Arguments</span>
+      <span class="value">None</span>
+    </li>
+    {{- end }}
+
+    {{- with .Results }}
+    <li>
+      <span class="type pill">Results</span>
+      <ol>
+      {{- range . }}
+        <li class="flex">
+          <span class="id"></span>
+          {{ render . }}
+        </li>
+      {{- end -}}
+      </ol>
+    </li>
+    {{- else -}}
+    <li class="flex">
+      <span class="type">Results</span>
+      <span class="value">None</span>
+    </li>
+    {{- end }}
+  </ul>
+</div>

_docs/generator/doc.join.struct-definition.tmpl

@@ -0,0 +1,4 @@
+<div class="flex join-point struct-definition">
+  <span class="type">Definition of</span>
+  {{ render .TypeName }}
+</div>

_docs/generator/doc.join.struct-literal.tmpl

@@ -0,0 +1,25 @@
+<div class="join-point struct-literal">
+  <div class="flex">
+    <span class="type">Struct literal</span>
+    {{ render .TypeName }}
+  </div>
+  <ul>
+  <li class="flex"><span class="type pill">
+    {{- if eq .Match 0 -}}
+    Pointer or Value
+    {{- else if eq .Match 1 -}}
+    Value
+    {{- else if eq .Match 2 -}}
+    Pointer
+    {{- else -}}
+    {{ .Match }}
+    {{- end -}}
+  </span></li>
+  {{- with .Field }}
+    <li class="flex">
+    <span class="type">Including field</span>
+    <code>{{ . }}</code>
+    </li>
+  {{- end -}}
+  </ul>
+</div>

_docs/generator/doc.join.test-main.tmpl

@@ -0,0 +1,4 @@
+<div class="flex join-point test-main">
+  <span class="type">Is test <tt>main</tt></span>
+  <code>{{ . }}</code>
+</div>

_docs/generator/doc.join.type-name.tmpl

@@ -0,0 +1,7 @@
+{{- "{{" -}}
+<godoc {{ with .ImportPath -}}
+  import-path="{{ . }}" package="{{ packageName . }}"
+  {{- end }} name="{{ .Name }}"
+  {{- if .Pointer }} prefix="*"{{ end -}}
+>
+{{- "}}" -}}

_docs/generator/doc.join.value-declaration.tmpl

@@ -0,0 +1,4 @@
+<div class="flex join-point value-declaration">
+  <span class="type">Package-level <code style="display:inline">const</code> or <code style="display:inline">var</code></span>
+  {{ render .TypeName }}
+</div>

_docs/generator/doc.md.tmpl

@@ -0,0 +1,49 @@
+---
+title: {{ .Title }}
+subtitle: {{ .PkgPath }}
+---
+{{ $single := eq (len .Files) 1 }}
+Those integration{{ if not $single }}s{{ end }} are enabled by having the
+following `import` in the project's `orchestrion.tool.go` file:
+
+```go
+import (
+	_ "{{ .PkgPath }}"
+)
+```
+
+---
+
+{{ range .Files -}}
+{{- if not $single -}}
+## {{ .Name }}
+{{ end -}}
+{{ .Description }}
+{{- range .Aspects }}
+
+### {{ .ID }}
+
+<div class="hextra-cards hx-mt-4 hx-gap-4 hx-grid" style="--hextra-cards-grid-cols: 1;">
+  <div class="aspect hextra-card hx-group hx-flex hx-flex-col hx-justify-start hx-overflow-hidden hx-rounded-lg hx-border hx-border-gray-200 hx-text-current hx-no-underline dark:hx-shadow-none hover:hx-shadow-gray-100 dark:hover:hx-shadow-none hx-shadow-gray-100 active:hx-shadow-sm active:hx-shadow-gray-200 hx-transition-all hx-duration-200">
+    <div>
+      <span class="hextra-card-icon hx-flex hx-font-semibold hx-items-start hx-gap-2 hx-p-4 hx-text-gray-700 hover:hx-text-gray-900 dark:hx-text-neutral-200 dark:hover:hx-text-neutral-50">
+        {{ `{{<iconSVG "search-circle">}}` | safe }} Join Point
+      </span>
+      <div class="root hextra-card-subtitle hx-font-normal hx-px-4 hx-mb-4 hx-mt-2">
+        {{- "\n" }}{{ render .JoinPoint | trim }}
+      </div>
+    </div>
+    {{- range .Advice }}
+    <div class="hx-border-t">
+      <span class="hextra-card-icon hx-flex hx-font-semibold hx-items-start hx-gap-2 hx-p-4 hx-text-gray-700 hover:hx-text-gray-900 dark:hx-text-neutral-200 dark:hover:hx-text-neutral-50">
+        {{ `{{<iconSVG "chip">}}` | safe }} Advice
+      </span>
+      <div class="hextra-card-subtitle hx-font-normal hx-px-4 hx-mb-4 hx-mt-2">
+        {{- "\n" }}{{ render . | trim }}
+      </div>
+    </div>
+    {{- end }}
+  </div>
+</div>
+{{ end }}
+{{ end -}}