Compute extensibility documentation update

.github/scripts/generate_resource_references.py

@@ -22,13 +22,52 @@
 
 hugo_template = """---
 type: docs
-title: "Reference: {}"
+title: "{}"
 linkTitle: "{}"
-description: "Detailed reference documentation for {}"
+description: "Reference documentation for {}"
 ---
 
 """
 
+# Namespace segment display-name overrides, used for capitalization that does
+# not follow simple title-casing (e.g. "ai" -> "AI").
+namespace_segment_overrides = {"ai": "AI"}
+
+# Namespace-parent directories to skip. The legacy "applications" tree holds the
+# retired Applications.* resource types, which are no longer documented.
+excluded_namespace_parents = {"applications"}
+
+def display_name(namespace):
+    return ".".join(
+        namespace_segment_overrides.get(segment, segment.capitalize())
+        for segment in namespace.split(".")
+    )
+
+# Top-level section index for the flattened resource schema tree. The
+# namespace-parent directory level (e.g. "radius") is flattened away so the
+# namespaces appear directly under a single "Resource schemas" section.
+section_index_template = """---
+type: docs
+title: "Resource Types"
+linkTitle: "Resource Types"
+description: "Schema reference for built-in Resource Types"
+weight: 200
+---
+
+## Introduction
+
+Resource Types define the schema for the resources developers use to model their applications—the properties you can configure, the values Radius returns, and the API versions each type supports. For a deeper explanation of what Resource Types are and how they abstract the underlying infrastructure, see the [Resource Types concepts]({{< ref "concepts/resource-types" >}}) page.
+
+`Radius.Core` Resource Types are embedded in the Radius control plane. All other Resource Types are sourced from the [resource-types-contrib](https://github.com/radius-project/resource-types-contrib) repository.
+
+All of the schema information on these pages is also available directly from your environment using [`rad resource-type list`]({{< ref rad_resource-type_list >}}) and [`rad resource-type show`]({{< ref rad_resource-type_show >}}), as well as through the [Radius Dashboard]({{< ref "/guides/installation/dashboard/overview" >}}).
+
+## How this section is organized
+
+Resource Types are organized first by namespace (such as `Radius.Core`, `Radius.Compute`, and `Radius.Data`) and then by API version (for example, `2025-08-01-preview`). Open a Resource Type to view its schema reference, which documents the resource's properties, including which fields are required and read-only.
+
+"""
+
 # Ensure that the script is called with the correct number of arguments
 if len(sys.argv) != 3:
     print("Usage: python generate_resource_references.py <source_directory> <target_directory>")
@@ -53,16 +92,19 @@
     print("No namespace parents found in source directory: {}".format(source_directory))
     sys.exit(1)
 
+# Create the top-level "Resource schemas" section index.
+os.makedirs(target_directory, exist_ok=True)
+with open(os.path.join(target_directory, '_index.md'), 'w') as f:
+    f.write(section_index_template)
+
 # Iterate through each namespace parent directory for each namespace
 for namespace_parent in namespace_parents:
     if not os.path.isdir(os.path.join(source_directory, namespace_parent)):
         continue
 
-    # Create _index.md file for namespace parent
-    target_namespace_parent_dir = os.path.join(target_directory, namespace_parent, '_index.md')
-    os.makedirs(os.path.dirname(target_namespace_parent_dir), exist_ok=True)
-    with open(target_namespace_parent_dir, 'w') as f:
-        f.write(hugo_template.format(namespace_parent, namespace_parent, namespace_parent))
+    # Skip retired namespace-parent trees (e.g. legacy Applications.* types).
+    if namespace_parent in excluded_namespace_parents:
+        continue
 
     namespaces = os.listdir(os.path.join(source_directory, namespace_parent))
     if not namespaces:
@@ -73,11 +115,11 @@
         if not os.path.isdir(os.path.join(source_directory, namespace_parent, namespace)):
             continue
 
-        # Create _index.md file for namespace
-        target_namespace_dir = os.path.join(target_directory, namespace_parent, namespace, '_index.md')
+        # Create _index.md file for namespace (flattened directly under target)
+        target_namespace_dir = os.path.join(target_directory, namespace, '_index.md')
         os.makedirs(os.path.dirname(target_namespace_dir), exist_ok=True)
         with open(target_namespace_dir, 'w') as f:
-            f.write(hugo_template.format(namespace, namespace, namespace))
+            f.write(hugo_template.format(display_name(namespace), display_name(namespace), namespace))
 
         api_versions = os.listdir(os.path.join(source_directory, namespace_parent, namespace))
         if not api_versions:
@@ -89,7 +131,7 @@
                 continue
 
             # Create _index.md file for API version
-            target_api_version_dir = os.path.join(target_directory, namespace_parent, namespace, api_version, '_index.md')
+            target_api_version_dir = os.path.join(target_directory, namespace, api_version, '_index.md')
             os.makedirs(os.path.dirname(target_api_version_dir), exist_ok=True)
             with open(target_api_version_dir, 'w') as f:
                 f.write(hugo_template.format(api_version, api_version, api_version))
@@ -105,9 +147,10 @@
 
                 resource_name = resource_markdown_file.split(".")[0]
                 print("Processing resource: {}/{}@{}".format(namespace, resource_name, api_version))
-                target_resource_dir = os.path.join(target_directory, namespace_parent, namespace, api_version, resource_name)
+                target_resource_dir = os.path.join(target_directory, namespace, api_version, resource_name)
 
-                hugo_content = hugo_template.format('{}/{}@{}'.format(namespace, resource_name, api_version), resource_name, '{}/{}@{}'.format(namespace, resource_name, api_version))
+                qualified_name = '{}/{}@{}'.format(display_name(namespace), resource_name, api_version)
+                hugo_content = hugo_template.format(qualified_name, resource_name, qualified_name)
                 hugo_content += "{{< schemaExample >}}\n\n"
 
                 ## Check if a Bicep file exists for the resource

docs/assets/scss/_code.scss

@@ -1,18 +1,5 @@
 // Code formatting.
 
-.highlight .copy-icon {
-    position: absolute;
-    right: 20px;
-    top: 18px;
-    opacity: 0.7;
-}
-
-
-.highlight pre {
-    /* Avoid pushing up the copy buttons. */
-    margin: 0;
-}
-
 .td-content {
 
     // Highlighted code.

docs/assets/scss/_content.scss

@@ -44,14 +44,47 @@
         @extend .img-fluid;
     }
 
-    > table {
+    > table:not(.td-initial) {
         @extend .table-striped;
 
-        @extend .table-responsive;
-
         @extend .table-bordered;
 
         @extend .table;
+
+        // Use a fixed layout so columns get predictable widths and don't
+        // collapse to fit long unbreakable tokens (e.g. resource IDs). We
+        // deliberately do NOT use Bootstrap's `.table-responsive` (which sets
+        // `display: block` and adds horizontal scrolling); instead long content
+        // wraps within its cell. The `:not(.td-initial)` qualifier matches the
+        // specificity of Docsy's own responsive-table rule so `display: table`
+        // wins the cascade.
+        display: table;
+        table-layout: fixed;
+        width: 100%;
+
+        // Long tokens like resource IDs wrap within their cell instead of
+        // forcing the table wide, while normal words break only at spaces.
+        td, th {
+            overflow-wrap: anywhere;
+            word-break: normal;
+        }
+
+        // Give the columns explicit widths so a long unbreakable token (e.g. a
+        // resource ID) in one column can't hog the table width and collapse the
+        // others. The last column takes the remaining space and wraps its
+        // content. "Description" is only pinned in 4-column tables (where it is
+        // not the last column); in 3-column tables it takes the remaining space.
+        th:first-child, td:first-child {
+            width: 15%;
+        }
+
+        th:nth-child(2), td:nth-child(2) {
+            width: 10%;
+        }
+
+        th:nth-child(3):not(:last-child), td:nth-child(3):not(:last-child) {
+            width: 40%;
+        }
     }
 
     > blockquote {

docs/assets/scss/_styles_project.scss

@@ -2,6 +2,19 @@
 @import "sidebar-tree";
 @import "content";
 
+// Code blocks use a dark syntax theme, so Docsy's default (dark) copy-to-clipboard
+// button is nearly invisible against them until hovered. Use a light color so the
+// button stays visible at all times, like other docs sites.
+.td-content .highlight pre button.td-click-to-copy {
+    color: rgba($white, 0.6);
+
+    &:hover,
+    &:active {
+        color: $white;
+        background-color: rgba($white, 0.15);
+    }
+}
+
 .td-navbar .navbar-brand__name {
     display: none;
 }

docs/content/concepts/_index.md

@@ -10,7 +10,7 @@ weight: 20
 
 Radius is a platform for defining and deploying applications and infrastructure to any cloud. It is a central component of modern-day internal developer platforms (IDPs). It allows platform engineers to define resource types for developers to use when building their applications, and separately, the implementation of those resource types using existing Infrastructure as Code (IaC) templates and modules. Additionally, Radius enables platform engineers to define logical environments with specific deployment targets (e.g., a specific cloud provider region), each with their own IaC implementation.
 
-This page provides a conceptual overview of Radius. It describes Radius' logical components, technical architecture and how Radius relates to other IDP components. It is accompanied by additional concept pages focused on each of the core components: Resource Types, Recipes, Environments, and Applications. If you are new to Radius, you are encouraged to complete the [Quick Start]({{< ref "quick-start" >}}). Then, after reading the concept documentation, complete the end-to-end [tutorial]({{< ref "tutorials" >}}).
+This page provides a conceptual overview of Radius. It describes Radius' logical components, technical architecture, and how Radius relates to other IDP components. It is accompanied by additional concept pages focused on each of the core components: Resource Types, Recipe Packs, Environments, and Applications. If you are new to Radius, you are encouraged to complete the [Quick Start]({{< ref "quick-start" >}}). Then, after reading the concept documentation, complete the end-to-end [tutorial]({{< ref "tutorials" >}}).
 
 ## IDP reference architecture
 
@@ -38,17 +38,19 @@ Radius is designed around a small number of core components. In order to enforce
 
 #### Resource Types
 
-Resource Types define the abstraction for a resource that will exist in the real world when deployed. Resource Types represent the **interface**, or contract, between developers and the platform. Since they are abstract and application oriented, there is only one Resource Type defined within Radius for each application resource. For example, a platform engineer may define a PostgreSQL database Resource Type which is an application-oriented abstraction of a one of the many ways of deploying an PostgreSQL database. Resource Types are defined conceptually by what they represent, but concretely by their name, API version, and their schema. The schema contains the set of required and optional properties which are used by developers when defining their application.
+Resource Types define the abstraction for a resource that will exist in the real world when deployed. Resource Types represent the **interface**, or contract, between developers and the platform. Since they are abstract and application oriented, there is only one Resource Type defined within Radius for each application resource. For example, a platform engineer may define a PostgreSQL database Resource Type which is an application-oriented abstraction of one of the many ways of deploying a PostgreSQL database. Resource Types are defined conceptually by what they represent, but concretely by their name, API version, and their schema. The schema contains the set of required and optional properties which are used by developers when defining their application.
 
-#### Recipes
+#### Recipe Packs
 
-While Resource Types define the interface, Recipes define the resource deployment **implementation**. Radius supports deploying resources using either Terraform or Bicep. The term *recipe* is used as a generic term to refer to both a Terraform configuration or a Bicep template.
+While Resource Types define the interface, Recipe Packs define the resource deployment **implementation**. A Recipe Pack is a simple manifest whose primary property is a set of recipes, one for each Resource Type. The term *recipe* is used as a generic term to refer to both a Terraform configuration or a Bicep template. For each Resource Type, the Recipe Pack specifies the Terraform configuration or Bicep template used to deploy that type, along with recipe parameter values that Radius will pass to the recipe at deploy-time. One or more Recipe Packs are then referenced in an Environment definition.
 
-Recipes are not tightly coupled with Radius or the Resource Type. In most circumstances, an existing Terraform configuration or Bicep template can be used as a Recipe with slight modifications to ensure the properties in the Resource Type map to the Terraform variables or Bicep parameters.
+Recipes are not tightly coupled with Radius or the Resource Type. In most circumstances, an existing Terraform configuration or Bicep template can be used as a recipe with slight modifications to ensure the properties in the Resource Type map to the Terraform variables or Bicep parameters.
 
 #### Environments
 
-Environments are where Resource Types, Recipes, and cloud providers come together. An Environment defines where applications are deployed; i.e., a landing zone for applications. Specifically, a Kubernetes namespace, an AWS account and region, or an Azure subscription and resource group. Critically, the Environment also defines the set of Recipes to be used for each Resource Type. By assigning Recipes at the Environment level, it is possible for each Environment to have a unique set of Recipes. Finally, each Recipe in an Environment definition can also have Environment-level Recipe parameters. Recipe parameters are useful for injecting additional environmental information into the Recipe.
+Environments are where Resource Types, Recipe Packs, and cloud providers come together. An Environment defines where applications are deployed; i.e., a landing zone for applications. Specifically, a Kubernetes namespace, an AWS account, region, and EKS cluster, or an Azure subscription, resource group, and AKS cluster. The Kubernetes cluster where the Radius control plane runs is independent of where application containers are deployed, so a single Radius installation can deploy applications to many different clusters. Critically, the Environment also defines which Recipe Packs are used to deploy resources. By assigning Recipe Packs at the Environment level, it is possible for each Environment to have a unique set of recipes.
+
+Finally, within the Environment definition, Environment-level recipe parameters can be defined. Recipe parameters are useful for injecting additional environmental information into the recipe such as if the environment is production or non-production. These parameters will override parameters defined within the Recipe Pack.
 
 #### Resource Groups
 
@@ -62,9 +64,9 @@ When a developer requests a resource to be deployed, those resources are not dep
 
 #### Applications and resources
 
-Developers build applications. But when they deploy those applications to Kubernetes or other container platforms, the notion of an application is typically lost. Developers are left with essentially a flat list of resources. In the best case, the resources are annotated with the application name, but not always. This makes it challenging for developers and SREs to understand what resources belong to what applications. 
+Developers build applications. But when they deploy those applications to Kubernetes or other container platforms, the notion of an application is typically lost. Developers are left with essentially a flat list of resources. In the best case, the resources are annotated with the application name, but not always. This makes it challenging for developers and SREs to understand what resources belong to what applications.
 
-Radius takes a different approach and makes the application a first-class resource. With Radius, developers first define an Application resource, then add resources to that Application such as containers and databases. All resources belong to an Application (with some exceptions for resources shared across applications such as shared storage). When an Application is deployed to an Environment, the Application's abstract resource definitions are *implemented* by the platform-specific Recipes in the Environment.
+Radius takes a different approach and makes the application a first-class resource. With Radius, developers first define an Application resource, then add resources to that Application such as containers and databases. All resources belong to an Application (with some exceptions for resources shared across applications such as shared storage). When an Application is deployed to an Environment, the Application's abstract resource definitions are *implemented* by the platform-specific recipes in the Recipe Packs assigned to the Environment.
 
 ## Technical architecture
 
@@ -100,7 +102,7 @@ The Controller component is an internal component that handles miscellaneous fun
 
 ### Git repository and OCI registry
 
-When Radius deploys a resource using Terraform or Bicep, the Applications and Dynamic RP container must have access to the specified Recipe. Therefore, a Git repository is used to store Terraform configurations and an OCI registry is used to store Bicep templates. Radius does not run Recipes off the local workstation's file system.
+When Radius deploys a resource using Terraform or Bicep, the Applications and Dynamic RP container must have access to the specified recipe. Therefore, a Git repository is used to store Terraform configurations and an OCI registry is used to store Bicep templates. Radius does not run recipes off the local workstation's file system.
 
 ## Next Steps
 

docs/content/concepts/applications/index.md

@@ -5,7 +5,7 @@ linkTitle: "Applications"
 description: "How Radius manages applications"
 weight: 40
 aliases:
-    - /content/guides/author-apps/applications/overview
+    - /content/guides/applications/applications/overview
 ---
 
 A Radius Application is a resource that is a parent to other resources that make up the application. Applications and its resources are defined in an application definition file using the Bicep Infrastructure as Code (IaC) language. Since applications are a first-class Resource Type in Radius, developers perform operations on applications rather than individual resources. When deploying resources, developers simply deploy the Application. Radius also tracks all deployed resources and their dependencies in a graph. Developers can add to the graph by expressing explicit dependencies such as a container relying on a database.