Documentation Generation

[katbyte]

Generate Documentation from.. ?

most likely this will involve a layer of "known good docs" persisted in the c# data layer that is used to add descriptions to terraform schema and generate documentation files. This depends on #1107

[tombuildsstuff]

Done some initial scaffolding of this in #1212, this isn't doing much yet - but should serve as a foundation for adding this

[tombuildsstuff]

The Data API now exposes this information as a part of the Terraform Endpoint (/v1/resource-manager/services/Compute/terraform):

The Resource Summary is (currently hard-coded in the API, but should likely be added to the Terraform Definition for each Service):

  "resources": {
    "virtual_machine": {
      "...": "...",
      "displayName": "Resource Group",
      "documentation": {
        "category": "Example Category",
        "description": "Some Description for this Resource",
        "exampleUsageHcl": "\nresource \u0022example_resource\u0022 \u0022example\u0022 {\n    example_field = \u0022...\u0022\n}\n"
      },
      "...": "...",

The Example Usage above can be sourced from the Basic Test Template, perhaps @mbfrahry could take a look into that one next?

---

Documentation for each field can be found against the Schema Model for this API too:

"schemaModelName": "ResourceGroupResourceSchema",
      "schemaModels": {
        "ResourceGroupResourceSchema": {
          "fields": {
            "Location": {
              "objectDefinition": {
                "nestedObject": null,
                "referenceName": null,
                "type": "Location"
              },
              "computed": false,
              "forceNew": true,
              "hclName": "location",
              "optional": false,
              "required": true,
              "documentation": {
                "markdown": null
              },
              "mappings": null,
              "validation": null
            },
            "Name": {
              "objectDefinition": {
                "nestedObject": null,
                "referenceName": null,
                "type": "String"
              },
              "computed": false,
              "forceNew": true,
              "hclName": "name",
              "optional": false,
              "required": true,
              "documentation": {
                "markdown": null
              },
              "mappings": null,
              "validation": null
            },
            "Tags": {
              "objectDefinition": {
                "nestedObject": null,
                "referenceName": null,
                "type": "Tags"
              },
              "computed": false,
              "forceNew": false,
              "hclName": "tags",
              "optional": true,
              "required": false,
              "documentation": {
                "markdown": null
              },
              "mappings": null,
              "validation": null
            }
          }
        }
      },

Whilst in this example the markdown fields are null, these will be output as a string description of the resource - namely without the valid values, or "changing the value for this field forces a new resource to be created" for this field.

Some hypothetical examples here:

• The name for this {Resource Name}.
• The ID of the {Parent Resource Name} within which this {Resource Name} should exist.
• A list of '{name}' blocks which enable configuring {thing}. (where ' = a code quote)

Validation still needs to be plumbed through, but in time we'll support validation against each field, which'll likely supports:

{
  "type": "FixedValues",
  "values": [
    "Value1",
    "Value2"
  ]
}

{
  "type": "Range",
  "values": [
    1, // min
    2 // max
  ]
}

As such we should be able to populate the "Possible values are X, Y and Z" component from the additional metadata in the validation details?

[tombuildsstuff]

This has been shipping for quite a while now.