doc/userguide: generate eve documentation

Add EVE documentation for QUIC and Pgsql to their respective sections of
the userguide.

Also add a complete EVE reference as an appendix.

Other protocols can be done, but its a manual process to document in the
schema, then add the glue to pull them into the documentation.

Currently the generated files need to be manually generated and
committed to git for ReadTheDocs to pick them up.

doc/userguide/Makefile.am

@@ -1,4 +1,5 @@
 EXTRA_DIST = \
+	_generated \
 	_static \
 	3rd-party-integration \
 	acknowledgements.rst \
@@ -7,6 +8,7 @@ EXTRA_DIST = \
 	conf.py \
 	configuration \
 	devguide \
+	evedoc.py \
 	file-extraction \
 	index.rst \
 	upgrade \
@@ -88,6 +90,18 @@ $(dist_man1_MANS): _build/man
 
 man: $(dist_man1_MANS)
 
+# For the generated EVE schema docs, we have to list each one so they
+# will generated for the "dist".
+EXTRA_DIST +=	_generated/eve-index.rst \
+	_generated/quic.rst \
+	_generated/pgsql.rst
+
+generate:
+	mkdir -p _generated
+	./evedoc.py --output _generated/eve-index.rst ../../etc/schema.json
+	./evedoc.py --output _generated/quic.rst --object quic ../../etc/schema.json
+	./evedoc.py --output _generated/pgsql.rst --object pgsql ../../etc/schema.json
+
 # Remove build artifacts that aren't tracked by autotools.
 clean-local:
 	rm -rf $(top_builddir)/doc/userguide/_build

doc/userguide/appendix/eve-index.rst

@@ -0,0 +1,7 @@
+EVE Index
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+.. include:: ../_generated/eve-index.rst

doc/userguide/appendix/index.rst

@@ -0,0 +1,7 @@
+Appendix
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   eve-index

doc/userguide/conf.py

@@ -338,3 +338,11 @@ def setup(app):
     "sysconfdir": os.getenv("sysconfdir", "/etc"),
     "localstatedir": os.getenv("localstatedir", "/var"),
 }
+
+# Custom code generate some documentation.
+# evedoc = "./evedoc.py"
+# eve_schema = "../../etc/schema.json"
+# os.makedirs("_generated", exist_ok=True)
+# subprocess.call([evedoc, "--output", "_generated/eve-index.rst", eve_schema])
+# for proto in ["quic", "pgsql"]:
+#     subprocess.call([evedoc, "--output", "_generated/{}.rst".format(proto), "--object", proto, eve_schema])

doc/userguide/index.rst

@@ -34,4 +34,5 @@ This is the documentation for Suricata |version|.
    acknowledgements
    licenses/index.rst
    devguide/index.rst
-   verifying-source-files
+   verifying-source-files
+   appendix/index.rst

doc/userguide/output/eve/eve-json-format.rst

@@ -2682,6 +2682,10 @@ References:
 .. _PostgreSQL message format - BackendKeyData: https://www.postgresql.org/docs
    /current/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-BACKENDKEYDATA
 
+Field Reference
+~~~~~~~~~~~~~~~
+
+.. include:: ../../_generated/pgsql.rst
 
 Event type: IKE
 ---------------
@@ -2937,6 +2941,11 @@ Example of QUIC logging with CYU, JA3 and JA4 hashes (note that the JA4 hash is
     "ja4": "q13d0310h3_55b375c5d22e_cd85d2d88918"
   }
 
+Output Reference
+~~~~~~~~~~~~~~~~
+
+.. include:: ../../_generated/quic.rst
+
 Event type: DHCP
 -----------------
 
@@ -3048,4 +3057,3 @@ Example of ARP logging: request and response
     "dest_mac": "00:1d:09:f0:92:ab",
     "dest_ip": "10.10.10.1"
   }
-

etc/Makefile.am

@@ -1,6 +1,7 @@
 etcdatadir =	$(datadir)/suricata
 
-EXTRA_DIST =	suricata.logrotate.in \
+EXTRA_DIST =	schema.json \
+		suricata.logrotate.in \
 		suricata.service.in
 
 dist_etcdata_DATA =	classification.config \