[DOCS] - Authoring/Customization section needs better examples

[f5-applebaum]

Use Case:

User would like to author/customize fast templates. For example, as a final objective, one wants to customize the built-in "http" template: https://github.com/F5Networks/f5-appsvcs-templates/blob/master/templates/bigip-fast-templates/http.yaml by: 1) Changing a default attribute on one of the objects 2) Adding a couple more parameters.

Problem Description:

The Section Describing how to customize templates: https://clouddocs.f5.com/products/extensions/f5-appsvcs-templates/latest/userguide/template-authoring.html#extended-types is confusing because when one wants to learn to start including other templates, led naturally by flow of the document, tends to continue with the generic example.

https://clouddocs.f5.com/products/extensions/f5-appsvcs-templates/latest/userguide/template-authoring.html#example

which

1) throws around a lot of possible extensions possible (ex. mst, yaml, json).

2) doesn't use the same variable names the built-in templates use:

"{{tenant_name}}": { "{{application_name}}": { ex. "{{tenant_name}}": { "{{app_name}}": {

which leads to non working examples....

2) references unknown items, ex. "f5 schema" ex. "BIG-IP FAST has support for enums and custom formats can be applied to the primitive types outlined in the previous section. The variable in the example is a service type from the f5 schema named service_type."

To build off the popular http example above. (which is yaml), one needs to include the following file:

https://github.com/F5Networks/f5-appsvcs-templates/blob/master/templates/bigip-fast-templates/f5.json

which the doc statement is referring to as the f5 schema, even though it's not mentioned in the include statements, there is no reference to at all, etc.

hence, the directory for your template set should include:

http.yaml
your-custom-parameters.json
f5.json
_as3.yaml
_virtual.yaml
etc. <- All the "_" include files mentioned in the http.yaml file

Documentation should ideally give example of the your-custom-parameters.json file:

ex.

{
  "my_custom_parameter_1": {
    "type": "string",
    "enum": [
      "value_1",
      "value_2",
      "value_3",
      "value_4",
      "value_5"
    ],
    "default": "value_1"
  },
  "my_custom_parameter_2": {
    "type": "string",
    "enum": [
      "value_6",
      "value_7",
      "value_8",
      "value_9",
      "value_10"
    ],
    "default": "value_6"
  }
}

that will be added to the schema.

And a couple of example template customizations to include these: ex.

contentType: application/json
title: Custom Application Template With Includes
description: Example Custom Template With Includes
allOf:
  - $ref: "_as3.yaml#"
  - $ref: "_virtual.yaml#/fastl4"
  - $ref: "_redirect_http.yaml#"
  - $ref: "_snat.yaml#"
  - $ref: "_persist.yaml#"
  - $ref: "_tls_server_profile.yaml#/fastl4"
  - $ref: "_tls_client_profile.yaml#/fastl4"
  - $ref: "_pool.yaml#"
  - $ref: "_monitors.yaml#/http"
  - $ref: "_http_profile.yaml#"
  - $ref: "_tcp_profile.yaml#/fastl4"
  - $ref: "_policy_endpoint.yaml#"
  - $ref: "_irule.yaml#"
  - $ref: "_vlan_allow.yaml#"
anyOf:
  - {}
  - $ref: "_analytics.yaml#/http"
  - $ref: "_analytics.yaml#/tcp"
  - $ref: "_security_policy.yaml#/fastl4"
  - $ref: "_security_firewall.yaml#"
  - $ref: "_security_dos.yaml#/fastl4"
  - $ref: "_shape.yaml#/fastl4"
  - $ref: "_telemetry.yaml#"
template: |
  {
    "{{tenant_name}}": {
      "{{app_name}}": {
        "{{app_name}}": {
            "remark": "Simple HTTP application with custom schema {{my_custom_parameter_1}}",
        }
      }
    }
  }

Request Summary: Essentially examples should be explicit, start off simple and build off one another.

ex. 1) How to customize a simple AS3 declaration and add custom parameters (where/how/etc.) 2) How to package the built-in http example 3) How to add custom parameters to the http example. Where to insert those values. 4) How to create your own includes