[DOCS] Reorganizing docs directory structure (elastic#1679)

* reorganize directory structure of docs * update links * top-level index is controlled by a template * move generated field files into a dedicated dir * account for new usage dir location in tooling * new fields/ locations handle new /fields location for index vs field doc files * correct the j2 index template * move images directory
ebeahan · Dec 6, 2021 · d92daa1 · d92daa1
1 parent 16fc898
commit d92daa1
Show file tree

Hide file tree

Showing 28 changed files with 22 additions and 24 deletions.
diff --git a/docs/artifacts.asciidoc → docs/additional-info/artifacts.asciidoc b/docs/artifacts.asciidoc → docs/additional-info/artifacts.asciidoc
diff --git a/docs/contributing.asciidoc → docs/additional-info/contributing.asciidoc b/docs/contributing.asciidoc → docs/additional-info/contributing.asciidoc
diff --git a/docs/faq.asciidoc → docs/additional-info/faq.asciidoc b/docs/faq.asciidoc → docs/additional-info/faq.asciidoc
diff --git a/docs/glossary.asciidoc → docs/additional-info/glossary.asciidoc b/docs/glossary.asciidoc → docs/additional-info/glossary.asciidoc
diff --git a/docs/additional.asciidoc → docs/additional-info/index.asciidoc b/docs/additional.asciidoc → docs/additional-info/index.asciidoc
diff --git a/docs/field-details.asciidoc → docs/fields/field-details.asciidoc b/docs/field-details.asciidoc → docs/fields/field-details.asciidoc
diff --git a/docs/field-values-usage.asciidoc → docs/fields/field-values-usage.asciidoc b/docs/field-values-usage.asciidoc → docs/fields/field-values-usage.asciidoc
diff --git a/docs/field-values.asciidoc → docs/fields/field-values.asciidoc b/docs/field-values.asciidoc → docs/fields/field-values.asciidoc
diff --git a/docs/fields.asciidoc → docs/fields/fields.asciidoc b/docs/fields.asciidoc → docs/fields/fields.asciidoc
diff --git a/docs/usage/README.md → docs/fields/usage/README.md b/docs/usage/README.md → docs/fields/usage/README.md
diff --git a/docs/usage/cloud.asciidoc → docs/fields/usage/cloud.asciidoc b/docs/usage/cloud.asciidoc → docs/fields/usage/cloud.asciidoc
diff --git a/docs/usage/service.asciidoc → docs/fields/usage/service.asciidoc b/docs/usage/service.asciidoc → docs/fields/usage/service.asciidoc
diff --git a/docs/usage/user.asciidoc → docs/fields/usage/user.asciidoc b/docs/usage/user.asciidoc → docs/fields/usage/user.asciidoc
diff --git a/docs/index.asciidoc b/docs/index.asciidoc
@@ -62,8 +62,8 @@ Guidelines].
 
 
 
-include::using.asciidoc[]
-include::fields.asciidoc[]
-include::field-values.asciidoc[]
-include::migrating.asciidoc[]
-include::additional.asciidoc[]
+include::using-ecs/index.asciidoc[]
+include::fields/fields.asciidoc[]
+include::fields/field-values.asciidoc[]
+include::migrating/index.asciidoc[]
+include::additional-info/index.asciidoc[]
diff --git a/docs/logstash.asciidoc.disabled b/docs/logstash.asciidoc.disabled
diff --git a/docs/converting.asciidoc → docs/migrating/converting.asciidoc b/docs/converting.asciidoc → docs/migrating/converting.asciidoc
diff --git a/docs/migrating.asciidoc → docs/migrating/index.asciidoc b/docs/migrating.asciidoc → docs/migrating/index.asciidoc
@@ -8,5 +8,4 @@ If you have a custom pipeline or application you would like to convert to ECS,
 please have a look at <<ecs-converting>>.
 
 include::products-solutions.asciidoc[]
-// include::logstash.asciidoc[]
 include::converting.asciidoc[]
diff --git a/docs/products-solutions.asciidoc → docs/migrating/products-solutions.asciidoc b/docs/products-solutions.asciidoc → docs/migrating/products-solutions.asciidoc
diff --git a/docs/using-conventions.asciidoc → docs/using-ecs/conventions.asciidoc b/docs/using-conventions.asciidoc → docs/using-ecs/conventions.asciidoc
diff --git a/docs/using-custom-fields.asciidoc → docs/using-ecs/custom-fields.asciidoc b/docs/using-custom-fields.asciidoc → docs/using-ecs/custom-fields.asciidoc
diff --git a/docs/using-getting-started.asciidoc → docs/using-ecs/getting-started.asciidoc b/docs/using-getting-started.asciidoc → docs/using-ecs/getting-started.asciidoc
diff --git a/docs/using-guidelines.asciidoc → docs/using-ecs/guidelines.asciidoc b/docs/using-guidelines.asciidoc → docs/using-ecs/guidelines.asciidoc
diff --git a/.../images/ecs-getting-started-dashboard.png → .../images/ecs-getting-started-dashboard.png b/.../images/ecs-getting-started-dashboard.png → .../images/ecs-getting-started-dashboard.png
diff --git a/docs/using.asciidoc → docs/using-ecs/index.asciidoc b/docs/using.asciidoc → docs/using-ecs/index.asciidoc
@@ -17,8 +17,8 @@ ECS fields, head over to <<ecs-custom-fields-in-ecs>>.
 <<ecs-mapping-network-events, Mapping network events>> provides a detailed walk-through of how to best map and
 categorize an example network event to the schema.
 
-include::using-getting-started.asciidoc[][]
-include::using-guidelines.asciidoc[]
-include::using-conventions.asciidoc[]
-include::using-custom-fields.asciidoc[]
-include::using-mapping-network-events.asciidoc[]
+include::getting-started.asciidoc[][]
+include::guidelines.asciidoc[]
+include::conventions.asciidoc[]
+include::custom-fields.asciidoc[]
+include::mapping-network-events.asciidoc[]
diff --git a/docs/using-mapping-network-events.asciidoc → ...using-ecs/mapping-network-events.asciidoc b/docs/using-mapping-network-events.asciidoc → ...using-ecs/mapping-network-events.asciidoc
diff --git a/scripts/generators/asciidoc_fields.py b/scripts/generators/asciidoc_fields.py
@@ -7,10 +7,13 @@
 
 
 def generate(nested, ecs_generated_version, out_dir):
+    # fields docs now have a dedicated docs subdir: docs/fields
+    fields_docs_dir = out_dir + '/fields'
+
     save_asciidoc(path.join(out_dir, 'index.asciidoc'), page_index(ecs_generated_version))
-    save_asciidoc(path.join(out_dir, 'fields.asciidoc'), page_field_index(nested, ecs_generated_version))
-    save_asciidoc(path.join(out_dir, 'field-details.asciidoc'), page_field_details(nested))
-    save_asciidoc(path.join(out_dir, 'field-values.asciidoc'), page_field_values(nested))
+    save_asciidoc(path.join(fields_docs_dir, 'fields.asciidoc'), page_field_index(nested, ecs_generated_version))
+    save_asciidoc(path.join(fields_docs_dir, 'field-details.asciidoc'), page_field_details(nested))
+    save_asciidoc(path.join(fields_docs_dir, 'field-values.asciidoc'), page_field_values(nested))
 
 # Helpers
 

diff --git a/scripts/generators/ecs_helpers.py b/scripts/generators/ecs_helpers.py
@@ -123,7 +123,7 @@ def path_exists_in_git_tree(tree, file_path):
 
 
 def usage_doc_files():
-    usage_docs_dir = os.path.join(os.path.dirname(__file__), '../../docs/usage')
+    usage_docs_dir = os.path.join(os.path.dirname(__file__), '../../docs/fields/usage')
     usage_docs_path = pathlib.Path(usage_docs_dir)
     if usage_docs_path.is_dir():
         return [x.name for x in usage_docs_path.glob('*.asciidoc') if x.is_file()]

diff --git a/scripts/templates/index.j2 b/scripts/templates/index.j2
@@ -62,8 +62,8 @@ Guidelines].
 
 
 
-include::using.asciidoc[]
-include::fields.asciidoc[]
-include::field-values.asciidoc[]
-include::migrating.asciidoc[]
-include::additional.asciidoc[]
+include::using-ecs/index.asciidoc[]
+include::fields/fields.asciidoc[]
+include::fields/field-values.asciidoc[]
+include::migrating/index.asciidoc[]
+include::additional-info/index.asciidoc[]