Add --force-docs option (#1879)

ebeahan · web-flow · commit 7c8cd173894f · 2022-04-14T12:45:21.000-05:00
* add --force-docs flag

* document --force-docs

* include mixing doc updates

* changelog
diff --git a/CHANGELOG.next.md b/CHANGELOG.next.md
@@ -85,6 +85,7 @@ Thanks, you're awesome :-) -->
 
 * Adding optional field attribute, `pattern`. #1834
 * Added support for re-using a fieldset as an array. #1838
+* Added `--force-docs` option to generator. #1879
 
 #### Improvements
 
diff --git a/Makefile b/Makefile
@@ -66,7 +66,7 @@ generate: generator
 # Run the new generator
 .PHONY: generator
 generator: ve
-	$(PYTHON) scripts/generator.py --strict --include "${INCLUDE}" --subset "${SUBSETS_DIR}"
+	$(PYTHON) scripts/generator.py --strict --include "${INCLUDE}" --subset "${SUBSETS_DIR}" --force-docs
 
 # Check Makefile format.
 .PHONY: makelint
diff --git a/USAGE.md b/USAGE.md
@@ -32,6 +32,7 @@ relevant artifacts for their unique set of data sources.
     + [Mapping & Template Settings](#mapping--template-settings)
     + [Strict Mode](#strict-mode)
     + [Intermediate-Only](#intermediate-only)
+    + [Force-docs](#force-docs)
 
 ## TLDR Example
 
@@ -444,3 +445,8 @@ This will cause an exception when running in strict mode.
 
 The `--intermediate-only` argument is used for debugging purposes. It only generates the ["intermediate files"](generated/ecs), `ecs_flat.yml` and `ecs_nested.yml`, without generating the rest of the artifacts.
 More information on the different intermediate files can be found in the generated directory's [README](generated/README.md).
+
+#### Force-docs
+
+By default, running the generator with `--subset`, `--include`, or `--exclude` flags will not generate the ECS docs in the `docs` directory. Use `--force-docs` to force the documentation to generate
+even if one of those flags is also present.
diff --git a/docs/fields/field-details.asciidoc b/docs/fields/field-details.asciidoc
@@ -6302,6 +6302,22 @@ type: keyword
 
 example: `v1beta1`
 
+| extended
+
+// ===============================================================
+
+|
+[[field-orchestrator-cluster-id]]
+<<field-orchestrator-cluster-id, orchestrator.cluster.id>>
+
+| Unique ID of the cluster.
+
+type: keyword
+
+
+
+
+
 | extended
 
 // ===============================================================
@@ -7156,24 +7172,6 @@ type: keyword
 
 example: `c2c455d9f99375d`
 
-| extended
-
-// ===============================================================
-
-|
-[[field-process-entry-meta-type]]
-<<field-process-entry-meta-type, process.entry_meta.type>>
-
-| beta:[ This field is beta and subject to change. ]
-
-The entry type for the entry session leader. Values include: init(e.g systemd), sshd, ssm, kubelet, teleport, terminal, console
-
-type: keyword
-
-
-
-
-
 | extended
 
 // ===============================================================
@@ -7316,32 +7314,6 @@ example: `4242`
 
 // ===============================================================
 
-|
-[[field-process-same-as-process]]
-<<field-process-same-as-process, process.same_as_process>>
-
-| beta:[ This field is beta and subject to change. ]
-
-This boolean is used to identify if a leader process is the same as the top level process.
-
-For example, if `process.group_leader.same_as_process = true`, it means the process event in question is the leader of its process group. Details under `process.*` like `pid` would be the same under `process.group_leader.*` The same applies for both `process.session_leader` and `process.entry_leader`.
-
-This field exists to the benefit of EQL and other rule engines since it's not possible to compare equality between two fields in a single document. e.g `process.entity_id` = `process.group_leader.entity_id` (top level process is the process group leader) OR `process.entity_id` = `process.entry_leader.entity_id` (top level process is the entry session leader)
-
-Instead these rules could be written like: `process.group_leader.same_as_process: true` OR `process.entry_leader.same_as_process: true`
-
-Note: This field is only set on `process.entry_leader`, `process.session_leader` and `process.group_leader`.
-
-type: boolean
-
-
-
-example: `True`
-
-| extended
-
-// ===============================================================
-
 |
 [[field-process-start]]
 <<field-process-start, process.start>>
@@ -9406,6 +9378,70 @@ example: `indicator_match_rule`
 
 // ===============================================================
 
+|
+[[field-threat-feed-dashboard-id]]
+<<field-threat-feed-dashboard-id, threat.feed.dashboard_id>>
+
+| The saved object ID of the dashboard belonging to the threat feed for displaying dashboard links to threat feeds in Kibana.
+
+type: keyword
+
+
+
+example: `5ba16340-72e6-11eb-a3e3-b3cc7c78a70f`
+
+| extended
+
+// ===============================================================
+
+|
+[[field-threat-feed-description]]
+<<field-threat-feed-description, threat.feed.description>>
+
+| Description of the threat feed in a UI friendly format.
+
+type: keyword
+
+
+
+example: `Threat feed from the AlienVault Open Threat eXchange network.`
+
+| extended
+
+// ===============================================================
+
+|
+[[field-threat-feed-name]]
+<<field-threat-feed-name, threat.feed.name>>
+
+| The name of the threat feed in UI friendly format.
+
+type: keyword
+
+
+
+example: `AlienVault OTX`
+
+| extended
+
+// ===============================================================
+
+|
+[[field-threat-feed-reference]]
+<<field-threat-feed-reference, threat.feed.reference>>
+
+| Reference information for the threat feed in a UI friendly format.
+
+type: keyword
+
+
+
+example: `https://otx.alienvault.com`
+
+| extended
+
+// ===============================================================
+
 |
 [[field-threat-framework]]
 <<field-threat-framework, threat.framework>>
diff --git a/docs/fields/fields.asciidoc b/docs/fields/fields.asciidoc
@@ -1,7 +1,7 @@
 [[ecs-field-reference]]
 == {ecs} Field Reference
 
-This is the documentation of ECS version 8.3.0-dev.
+This is the documentation of ECS version 8.4.0-dev.
 
 ECS defines multiple groups of related fields. They are called "field sets".
 The <<ecs-base,Base>> field set is the only one whose fields are defined
diff --git a/docs/index.asciidoc b/docs/index.asciidoc
@@ -13,7 +13,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 [[ecs-reference]]
 == Overview
 
-This is the documentation of ECS version 8.3.0-dev.
+This is the documentation of ECS version 8.4.0-dev.
 
 [float]
 === What is ECS?
diff --git a/scripts/generator.py b/scripts/generator.py
@@ -74,7 +74,7 @@ def main():
     es_template.generate_legacy(flat, ecs_generated_version, out_dir,
                                 args.mapping_settings, args.template_settings_legacy)
     beats.generate(nested, ecs_generated_version, out_dir)
-    if args.include or args.subset or args.exclude:
+    if (args.include or args.subset or args.exclude) and not args.force_docs:
         exit()
 
     ecs_helpers.make_dirs(docs_dir)
@@ -102,6 +102,8 @@ def argument_parser():
                         help='enforce strict checking at schema cleanup')
     parser.add_argument('--intermediate-only', action='store_true',
                         help='generate intermediary files only')
+    parser.add_argument('--force-docs', action='store_true',
+                        help='generate ECS docs even if --subset, --include, or --exclude are set')
     args = parser.parse_args()
     # Clean up empty include of the Makefile
     if args.include and [''] == args.include:
