Kubernetes operator page refers to API doc that can only be viewed as mostly unusable raw text view

[chalin]

To reproduce:

• Visit https://opentelemetry.io/docs/kubernetes/operator/automatic/#configure-automatic-instrumentation
• Click on the link in:

  This is done via the Instrumentation CRD.

• In GitHub you'll see:

  View raw
  (Sorry about that, but we can’t show files that are this big right now.)

Have you looked at the raw file? Doing so is far from user friendly:

# API Reference

Packages:

- [opentelemetry.io/v1alpha1](#opentelemetryiov1alpha1)
- [opentelemetry.io/v1beta1](#opentelemetryiov1beta1)

# opentelemetry.io/v1alpha1

Resource Types:

- [Instrumentation](#instrumentation)

- [OpAMPBridge](#opampbridge)

- [OpenTelemetryCollector](#opentelemetrycollector)

- [TargetAllocator](#targetallocator)




## Instrumentation
<sup><sup>[↩ Parent](#opentelemetryiov1alpha1 )</sup></sup>






Instrumentation is the spec for OpenTelemetry instrumentation.

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Type</th>
            <th>Description</th>
            <th>Required</th>
        </tr>
    </thead>
    <tbody><tr>
      <td><b>apiVersion</b></td>
      <td>string</td>
      <td>opentelemetry.io/v1alpha1</td>
      <td>true</td>
      </tr>
      <tr>
      <td><b>kind</b></td>
      <td>string</td>
      <td>Instrumentation</td>
      <td>true</td>
      </tr>
      <tr>
      <td><b><a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#objectmeta-v1-meta">metadata</a></b></td>
      <td>object</td>
      <td>Refer to the Kubernetes API documentation for the fields of the `metadata` field.</td>
      <td>true</td>
      </tr><tr>
        <td><b><a href="#instrumentationspec">spec</a></b></td>
        <td>object</td>
        <td>
          InstrumentationSpec defines the desired state of OpenTelemetry SDK and instrumentation.<br/>
        </td>
        <td>false</td>
      </tr><tr>
        <td><b>status</b></td>
        <td>object</td>
        <td>
          InstrumentationStatus defines status of the instrumentation.<br/>
        </td>
        <td>false</td>
      </tr></tbody>
</table>


### Instrumentation.spec
<sup><sup>[↩ Parent](#instrumentation)</sup></sup>
...

How can we do better? @open-telemetry/operator-approvers.

Related

• Context [chore] Ensure that external link fragments are valid #6196
• Previous attempt at resolving this (though I don't recommend that approach):
  • Add content/en/docs/kubernetes/operator/api.md #6104

[swiatekm]

This was caused by us adding a new CRD, and the updated markdown doc is apparently too big for Github to render. This was fixed in open-telemetry/opentelemetry-operator#3696, and each CRD now has its own API doc markdown file in https://github.com/open-telemetry/opentelemetry-operator/tree/main/docs/api. I think this will let us have more targeted links in the operator docs on opentelemetry.io as well.

[chalin]

Super!

Closed by:

• Split CRD documentation into separate files opentelemetry-operator#3696