From 3e67fc4ebe382c658181489b4927c5389ea43134 Mon Sep 17 00:00:00 2001
From: Mathieu Martin <mathieu.martin@elastic.co>
Date: Mon, 23 Mar 2020 11:39:31 -0400
Subject: [PATCH] Fix nested fields documentation (#784) (#795)

The Field Reuse section of docs was not documenting nested fields
correctly.

For example, if interface can be nested under `observer.ingress` and
`observer.egress`, the docs would display `observer.interface.*`,
instead of `observer.ingress.interface.*` and
`observer.egress.interface.*`.

This patch improves the docs by adding the full nesting path.

Co-authored-by: Adrian Serrano
---
 docs/field-details.asciidoc           | 40 +++++++++++++++++++++++----
 scripts/generators/asciidoc_fields.py | 23 ++++++++++-----
 2 files changed, 51 insertions(+), 12 deletions(-)

diff --git a/docs/field-details.asciidoc b/docs/field-details.asciidoc
index 3e0607d40a..a48292d54e 100644
--- a/docs/field-details.asciidoc
+++ b/docs/field-details.asciidoc
@@ -3316,6 +3316,12 @@ example: `ipv4`
 // ===============================================================
 
 
+| <<ecs-vlan,network.inner.vlan.*>>
+| Fields to describe observed VLAN information.
+
+// ===============================================================
+
+
 | <<ecs-vlan,network.vlan.*>>
 | Fields to describe observed VLAN information.
 
@@ -3537,26 +3543,38 @@ type: keyword
 // ===============================================================
 
 
+| <<ecs-interface,observer.egress.interface.*>>
+| Fields to describe observer interface information.
+
+// ===============================================================
+
+
+| <<ecs-vlan,observer.egress.vlan.*>>
+| Fields to describe observed VLAN information.
+
+// ===============================================================
+
+
 | <<ecs-geo,observer.geo.*>>
 | Fields describing a location.
 
 // ===============================================================
 
 
-| <<ecs-interface,observer.interface.*>>
+| <<ecs-interface,observer.ingress.interface.*>>
 | Fields to describe observer interface information.
 
 // ===============================================================
 
 
-| <<ecs-os,observer.os.*>>
-| OS fields contain information about the operating system.
+| <<ecs-vlan,observer.ingress.vlan.*>>
+| Fields to describe observed VLAN information.
 
 // ===============================================================
 
 
-| <<ecs-vlan,observer.vlan.*>>
-| Fields to describe observed VLAN information.
+| <<ecs-os,observer.os.*>>
+| OS fields contain information about the operating system.
 
 // ===============================================================
 
@@ -4563,6 +4581,18 @@ example: `/home/alice`
 // ===============================================================
 
 
+| <<ecs-code_signature,process.parent.code_signature.*>>
+| These fields contain information about binary code signatures.
+
+// ===============================================================
+
+
+| <<ecs-hash,process.parent.hash.*>>
+| Hashes, usually file hashes.
+
+// ===============================================================
+
+
 | <<ecs-pe,process.pe.*>>
 | These fields contain Windows Portable Executable (PE) metadata.
 
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
index 6faa689d7f..df5931bce8 100644
--- a/scripts/generators/asciidoc_fields.py
+++ b/scripts/generators/asciidoc_fields.py
@@ -122,13 +122,22 @@ def render_fieldset_reuse_section(fieldset, ecs_nested):
             fieldset_name=fieldset['name'],
             fieldset_title=fieldset['title']
         )
-
-        for nested_fs_name in sorted(fieldset['nestings']):
-            text += render_nesting_row({
-                'flat_nesting': "{}.{}.*".format(fieldset['name'], nested_fs_name),
-                'name': nested_fs_name,
-                'short': ecs_nested[nested_fs_name]['short']
-            })
+        rows = []
+        for nested_fs_name in fieldset['nestings']:
+            ecs = ecs_nested[nested_fs_name]
+            if 'reusable' in ecs:
+                target_fields = filter(lambda x: x == fieldset['name'] or x.startswith(
+                    fieldset['name'] + '.'), ecs['reusable']['expected'])
+            else:
+                target_fields = [fieldset['name']]
+            for field in target_fields:
+                rows.append({
+                    'flat_nesting': "{}.{}.*".format(field, nested_fs_name),
+                    'name': nested_fs_name,
+                    'short': ecs['short']
+                })
+        for row in sorted(rows, key=lambda x: x['flat_nesting']):
+            text += render_nesting_row(row)
         text += table_footer()
     return text