From a7c9b252be527fc79b87d16bb7287ffa156ccc8e Mon Sep 17 00:00:00 2001
From: Adam Souzis <adam@souzis.com>
Date: Thu, 3 Oct 2024 12:15:23 -0700
Subject: [PATCH] docs: re-arrange tosca reference pages

---
 docs/index.rst                 |  4 +--
 docs/toscaref.rst              |  2 +-
 docs/toscaref/spec-groups.rst  | 13 ++++++--
 docs/toscaref/spec-outputs.rst | 60 ++++++++++++----------------------
 4 files changed, 34 insertions(+), 45 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index a1a6ebba..8a1e7e65 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -32,6 +32,8 @@ Table of Contents
 
    TOSCA as Python <dsl.md>
 
+   toscaref.rst
+
    packages.rst
 
    secrets.rst
@@ -50,8 +52,6 @@ Table of Contents
 
    jsonschema.rst
 
-   toscaref.rst
-
    glossary.rst
 
    api.rst
diff --git a/docs/toscaref.rst b/docs/toscaref.rst
index d3b4a7a5..76298772 100644
--- a/docs/toscaref.rst
+++ b/docs/toscaref.rst
@@ -2,7 +2,7 @@
 TOSCA Language Reference
 ================================
 
-This section describes the YAML syntax of the TOSCA :tosca_spec:`Service templates<DEFN_ELEMENT_SERVICE_TEMPLATE>` 
+This section describes the syntax of the TOSCA :tosca_spec:`Service templates<DEFN_ELEMENT_SERVICE_TEMPLATE>`
 
 A service template is comprised of several high level sections:
 
diff --git a/docs/toscaref/spec-groups.rst b/docs/toscaref/spec-groups.rst
index 2d9331e1..64289e80 100644
--- a/docs/toscaref/spec-groups.rst
+++ b/docs/toscaref/spec-groups.rst
@@ -4,7 +4,9 @@ Groups
 ======
 
 ``groups`` provide a way of configuring shared behavior for different
-sets of ``node_templates``.
+sets of ``node_templates``.  Groups can optionally have a :ref:`type <group_types>` and properties.
+
+As an Unfurl extension, groups can have other groups as members.
 
 Example
 +++++++
@@ -13,10 +15,13 @@ Example
 
  groups:
    group1:
+     type: my_group_type
      members:
        - node_template_1
        - another_group
-
+   another_group:
+     members:
+       - node_template_2
 
 Definition
 +++++++++++
@@ -24,9 +29,11 @@ Definition
 +------------+----------+------+--------------------------------------+
 | Keyname    | Required | Type | Description                          |
 +============+==========+======+======================================+
++------------+----------+------+--------------------------------------+
+| type       | no       |string| The group's :ref:`type <group_types>`|
++------------+----------+------+--------------------------------------+
 | members    | yes      | list | A list of group members. Members are |
 |            |          |      | group or node template names.        |
 +------------+----------+------+--------------------------------------+
 | properties | no       | dict | A dict of properties.                |
 +------------+----------+------+--------------------------------------+
-
diff --git a/docs/toscaref/spec-outputs.rst b/docs/toscaref/spec-outputs.rst
index 7c560aac..66a48deb 100644
--- a/docs/toscaref/spec-outputs.rst
+++ b/docs/toscaref/spec-outputs.rst
@@ -33,7 +33,7 @@ Definition
      - no
      - string
      - An optional description for the output.
-   * - values
+   * - value
      - yes
      - <any>
      - The output value. May be anything from a simple value (e.g. port) to a complex value (e.g. hash with values). Output values can contain hard-coded values, inputs, properties and attributes.
@@ -44,44 +44,26 @@ Example
 
 .. code:: yaml
 
- tosca_definitions_version: tosca_dsl_1_3
-
- imports:
-   - http://<example URL>/types.yaml
-
- node_templates:
-   webserver_vm:
-     type: tosca.nodes.Compute
-   webserver:
-     type: tosca.nodes.WebServer
-     properties:
-         port: 8080
-
- outputs:
-     webapp_endpoint:
-         description: ip and port of the web application
-         value:
-             ip: { get_attribute: [webserver_vm, ip] }
-             port: { get_property: [webserver, port] }
-
-Outputs
-+++++++
-
-Outputs are recorded in the :ref:`ensemble.yaml<ensemble_yaml>` and is printed in the console after a job has completed as part of the job summary.
-
-.. code:: yaml
-
- status:
-   outputs:
-     url: https://demo.example.com
-   webapp_endpoint:
-        description: ip and port of the web application
-        value:
-            ip: { get_attribute: [webserver_vm, ip] }
-            port
- 
-Example
--------
+ topology_template:
+    node_templates:
+      webserver_vm:
+        type: tosca.nodes.Compute
+      webserver:
+        type: tosca.nodes.WebServer
+        properties:
+            port: 8080
+
+    outputs:
+        webapp_endpoint:
+            description: ip and port of the web application
+            value:
+                ip: { get_attribute: [webserver_vm, ip] }
+                port: { get_property: [webserver, port] }
+
+Job Status
+++++++++++
+
+Outputs are printed in the console after a job has completed as part of the job summary and recorded in the :ref:`ensemble.yaml<ensemble_yaml>`'s status section:
 
 .. code:: yaml