[9.0](backport #44793) [documentation][exported-fields] update autogeneration scripts to generate markdown (#44803)

* [documentation][exported-fields] update autogeneration scripts to generate markdown  (#44793)

* chore: port asciidoc scripts to markdown

* fix docs preview

* add meraki description

* make check

(cherry picked from commit 00dcc0c)

# Conflicts:
#	docs/reference/metricbeat/exported-fields-nats.md
#	libbeat/scripts/generate_fields_docs.py

* merge conflicts

* exported docs

---------

Co-authored-by: Vihas Makwana <[email protected]>
Co-authored-by: Vihas Makwana <[email protected]>

Author: mergify[bot]

dev-tools/mage/docs.go

@@ -66,7 +66,7 @@ func DocsIndexFile(file string) DocsOption {
 // Docs holds the utilities for building documentation.
 var Docs = docsBuilder{}
 
-// FieldDocs generates docs/fields.asciidoc from the specified fields.yml file.
+// FieldDocs generates exported-fields.md from the specified fields.yml file.
 func (docsBuilder) FieldDocs(fieldsYML string) error {
 	// Run the docs_collector.py script.
 	ve, err := PythonVirtualenv(false)
@@ -84,13 +84,15 @@ func (docsBuilder) FieldDocs(fieldsYML string) error {
 		return err
 	}
 
+	outputPath := filepath.Join(DocsDir(), "reference", BeatName)
+
 	// TODO: Port this script to Go.
-	log.Println(">> Generating docs/fields.asciidoc for", BeatName)
+	log.Println(">> Generating exported-fields.md for", BeatName)
 	return sh.Run(python, LibbeatDir("scripts/generate_fields_docs.py"),
-		fieldsYML,                     // Path to fields.yml.
-		BeatName,                      // Beat title.
-		esBeats,                       // Path to general beats folder.
-		"--output_path", OSSBeatDir()) // It writes to {output_path}/docs/fields.asciidoc.
+		fieldsYML,                   // Path to fields.yml.
+		BeatName,                    // Beat title.
+		esBeats,                     // Path to general beats folder.
+		"--output_path", outputPath) // It writes to {output_path}/exported-fields.md.
 }
 
 func (b docsBuilder) AsciidocBook(opts ...DocsOption) error {

docs/reference/auditbeat/exported-fields-auditd.md

@@ -3,6 +3,8 @@ mapped_pages:
   - https://www.elastic.co/guide/en/beats/auditbeat/current/exported-fields-auditd.html
 ---
 
+% This file is generated! See scripts/generate_fields_docs.py
+
 # Auditd fields [exported-fields-auditd]
 
 These are the fields generated by the auditd module.
@@ -49,10 +51,9 @@ alias to: user.saved.group.id
 alias to: user.filesystem.group.id
 
 
-
 ## name_map [_name_map]
 
-If `resolve_ids` is set to true in the configuration then `name_map` will contain a mapping of uid field names to the resolved name (e.g. auid → root).
+If `resolve_ids` is set to true in the configuration then `name_map` will contain a mapping of uid field names to the resolved name (e.g. auid -> root).
 
 **`user.name_map.auid`**
 :   type: alias
@@ -96,7 +97,6 @@ alias to: user.saved.group.name
 alias to: user.filesystem.group.name
 
 
-
 ## selinux [_selinux]
 
 The SELinux identity of the actor.
@@ -108,32 +108,31 @@ type: keyword
 
 
 **`user.selinux.role`**
-:   user’s SELinux role
+:   user's SELinux role
 
 type: keyword
 
 
 **`user.selinux.domain`**
-:   The actor’s SELinux domain or type.
+:   The actor's SELinux domain or type.
 
 type: keyword
 
 
 **`user.selinux.level`**
-:   The actor’s SELinux level.
+:   The actor's SELinux level.
 
 type: keyword
 
 example: s0
 
 
 **`user.selinux.category`**
-:   The actor’s SELinux category or compartments.
+:   The actor's SELinux category or compartments.
 
 type: keyword
 
 
-
 ## process [_process]
 
 Process attributes.
@@ -146,7 +145,6 @@ type: alias
 alias to: process.working_directory
 
 
-
 ## source [_source]
 
 Source that triggered the event.
@@ -157,7 +155,6 @@ Source that triggered the event.
 type: keyword
 
 
-
 ## destination [_destination]
 
 Destination address that triggered the event.
@@ -196,13 +193,12 @@ type: keyword
 example: success or fail
 
 
-
 ## actor [_actor]
 
 The actor is the user that triggered the audit event.
 
 **`auditd.summary.actor.primary`**
-:   The primary identity of the actor. This is the actor’s original login ID. It will not change even if the user changes to another account.
+:   The primary identity of the actor. This is the actor's original login ID. It will not change even if the user changes to another account.
 
 type: keyword
 
@@ -213,7 +209,6 @@ type: keyword
 type: keyword
 
 
-
 ## object [_object]
 
 This is the thing or object being acted upon in the event.
@@ -238,7 +233,6 @@ type: keyword
 type: keyword
 
 
-
 ## paths [_paths]
 
 List of paths associated with the event.
@@ -317,8 +311,7 @@ type: keyword
 type: keyword
 
 
-
-## data [_data_2]
+## data [_data]
 
 The data from the audit messages.
 
@@ -335,7 +328,7 @@ type: keyword
 
 
 **`auditd.data.acct`**
-:   a user’s account name
+:   a user's account name
 
 type: keyword
 
@@ -555,7 +548,7 @@ type: keyword
 
 
 **`auditd.data.audit_backlog_limit`**
-:   audit system’s backlog queue size
+:   audit system's backlog queue size
 
 type: keyword
 
@@ -591,7 +584,7 @@ type: keyword
 
 
 **`auditd.data.oauid`**
-:   object’s login user ID
+:   object's login user ID
 
 type: keyword
 
@@ -615,13 +608,13 @@ type: keyword
 
 
 **`auditd.data.vm-ctx`**
-:   the vm’s context string
+:   the vm's context string
 
 type: keyword
 
 
 **`auditd.data.opid`**
-:   object’s process ID
+:   object's process ID
 
 type: keyword
 
@@ -675,7 +668,7 @@ type: keyword
 
 
 **`auditd.data.range`**
-:   user’s SE Linux range
+:   user's SE Linux range
 
 type: keyword
 
@@ -705,7 +698,7 @@ type: keyword
 
 
 **`auditd.data.subj`**
-:   lspp subject’s context string
+:   lspp subject's context string
 
 type: keyword
 
@@ -723,13 +716,13 @@ type: keyword
 
 
 **`auditd.data.kernel`**
-:   kernel’s version number
+:   kernel's version number
 
 type: keyword
 
 
 **`auditd.data.ocomm`**
-:   object’s command line name
+:   object's command line name
 
 type: keyword
 
@@ -807,7 +800,7 @@ type: keyword
 
 
 **`auditd.data.iuid`**
-:   ipc object’s user ID
+:   ipc object's user ID
 
 type: keyword
 
@@ -837,7 +830,7 @@ type: keyword
 
 
 **`auditd.data.vm-pid`**
-:   vm’s process ID
+:   vm's process ID
 
 type: keyword
 
@@ -855,7 +848,7 @@ type: keyword
 
 
 **`auditd.data.oses`**
-:   object’s session ID
+:   object's session ID
 
 type: keyword
 
@@ -867,7 +860,7 @@ type: keyword
 
 
 **`auditd.data.igid`**
-:   ipc object’s group ID
+:   ipc object's group ID
 
 type: keyword
 
@@ -987,7 +980,7 @@ type: keyword
 
 
 **`auditd.data.audit_backlog_wait_time`**
-:   audit system’s backlog wait time
+:   audit system's backlog wait time
 
 type: keyword
 
@@ -1023,7 +1016,7 @@ type: keyword
 
 
 **`auditd.data.format`**
-:   audit log’s format
+:   audit log's format
 
 type: keyword
 
@@ -1035,7 +1028,7 @@ type: keyword
 
 
 **`auditd.data.tcontext`**
-:   the target’s or object’s context string
+:   the target's or object's context string
 
 type: keyword
 
@@ -1113,7 +1106,7 @@ type: keyword
 
 
 **`auditd.data.inode_gid`**
-:   group ID of the inode’s owner
+:   group ID of the inode's owner
 
 type: keyword
 
@@ -1203,7 +1196,7 @@ type: keyword
 
 
 **`auditd.data.audit_failure`**
-:   audit system’s failure mode
+:   audit system's failure mode
 
 type: keyword
 
@@ -1263,7 +1256,7 @@ type: keyword
 
 
 **`auditd.data.seuser`**
-:   user’s SE Linux user acct
+:   user's SE Linux user acct
 
 type: keyword
 
@@ -1359,7 +1352,7 @@ type: keyword
 
 
 **`auditd.data.list`**
-:   the audit system’s filter list number
+:   the audit system's filter list number
 
 type: keyword
 
@@ -1401,7 +1394,7 @@ type: keyword
 
 
 **`auditd.data.audit_enabled`**
-:   audit systems’s enable/disable status
+:   audit systems's enable/disable status
 
 type: keyword
 
@@ -1425,19 +1418,19 @@ type: keyword
 
 
 **`auditd.data.scontext`**
-:   the subject’s context string
+:   the subject's context string
 
 type: keyword
 
 
 **`auditd.data.tclass`**
-:   target’s object classification
+:   target's object classification
 
 type: keyword
 
 
 **`auditd.data.ver`**
-:   audit daemon’s version number
+:   audit daemon's version number
 
 type: keyword
 
@@ -1455,7 +1448,7 @@ type: keyword
 
 
 **`auditd.data.img-ctx`**
-:   the vm’s disk image context string
+:   the vm's disk image context string
 
 type: keyword
 
@@ -1479,7 +1472,7 @@ type: keyword
 
 
 **`auditd.data.inode_uid`**
-:   user ID of the inode’s owner
+:   user ID of the inode's owner
 
 type: keyword
 
@@ -1538,7 +1531,6 @@ type: alias
 alias to: error.message
 
 
-
 ## geoip [_geoip]
 
 The geoip fields are defined as a convenience in case you decide to enrich the data using a geoip filter in Logstash or an Elasticsearch geoip ingest processor.

docs/reference/auditbeat/exported-fields-beat-common.md

@@ -3,6 +3,8 @@ mapped_pages:
   - https://www.elastic.co/guide/en/beats/auditbeat/current/exported-fields-beat-common.html
 ---
 
+% This file is generated! See scripts/generate_fields_docs.py
+
 # Beat fields [exported-fields-beat-common]
 
 Contains common beat fields available in all event types.