Merge remote-tracking branch 'origin/topic/timw/rst-linting'

* origin/topic/timw/rst-linting:
  Regenerate spicy docs
  Regenerate docs for rst linting fixes from scripts and bifs
  Fix uses of backticks
  Add pre-commit for linting rst, fix colon issues
  Use :file: directive for all log files in non-generated code

Author: timwoj

.pre-commit-config.yaml

@@ -7,3 +7,11 @@ repos:
     - id: ruff-format
     - id: ruff
       args: [--fix]
+
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: v1.10.0
+  hooks:
+  - id: rst-directive-colons
+    stages: ["pre-commit"]
+  - id: rst-backticks
+    stages: ["pre-commit"]

cluster-setup.rst

@@ -177,7 +177,7 @@ Offloading and ethtool tuning
 While not specific to AF_PACKET, it is recommended to disable any offloading
 features provided by the network card or Linux networking stack when running
 Zeek. This allows to see network packets as they arrive on the wire.
-See this `blog post <https://blog.securityonion.net/2011/10/when-is-full-packet-capture-not-full.html`>_
+See this `blog post <https://blog.securityonion.net/2011/10/when-is-full-packet-capture-not-full.html>`_
 for more background
 
 Toggling these features can be done with the ``ethtool -K`` command, for example::
@@ -600,4 +600,3 @@ same packets multiple times with different tools.
 
        This issue has been fixed in all stable kernels for at least 5 years.
        You're unlikely to be affected.
-

customizations.rst

@@ -286,14 +286,14 @@ package helps you with that.
 Long Connections
 ----------------
 
-Zeek logs connection entries into the ``conn.log`` only upon termination
+Zeek logs connection entries into the :file:`conn.log` only upon termination
 or due to expiration of inactivity timeouts. Depending on the protocol and
 chosen timeout values this can significantly delay the appearance of a log
 entry for a given connection. The delay may be up to an hour for lingering
 SSH connections or connections where the final FIN or RST packets were missed.
 
-The `zeek-long-connections`_ package alleviates this by creating a ``conn_long.log``
-log with the same format as ``conn.log``, but containing entries for connections
+The `zeek-long-connections`_ package alleviates this by creating a :file:`conn_long.log`
+log with the same format as :file:`conn.log`, but containing entries for connections
 that have been existing for configurable intervals.
 By default, the first entry for a connection is logged after 10mins. Depending on
 the environment, this can be lowered as even a 10 minute delay may be significant

devel/plugins.rst

@@ -449,7 +449,7 @@ If your plugin isn't loading as expected, Zeek's debugging facilities
 can help illuminate what's going on. To enable, recompile Zeek
 with debugging support (``./configure --enable-debug``), and
 afterwards rebuild your plugin as well. If you then run Zeek with ``-B
-plugins``, it will produce a file ``debug.log`` that records details
+plugins``, it will produce a file :file:`debug.log` that records details
 about the process for searching, loading, and activating plugins.
 
 To generate your own debugging output from inside your plugin, you can
@@ -463,7 +463,7 @@ your plugin's debugging output with ``-B plugin-<name>``, where
 ``Configure()`` method, yet with the namespace-separator ``::``
 replaced with a simple dash. Example: If the plugin is called
 ``Demo::Rot13``, use ``-B plugin-Demo-Rot13``. As usual, the debugging
-output will be recorded to ``debug.log`` if Zeek's compiled in debug
+output will be recorded to :file:`debug.log` if Zeek's compiled in debug
 mode.
 
 Building Plugins Statically

devel/spicy/autogen/init-bare.zeek

@@ -23,7 +23,7 @@ export {
 # doc-options-end
 
 # doc-types-start
-    ## Result type for `Spicy::resource_usage()`. The values reflect resource
+    ## Result type for ``Spicy::resource_usage()``. The values reflect resource
     ## usage as reported by the Spicy runtime system.
     type ResourceUsage: record {
         user_time : interval;           ##< user CPU time of the Zeek process

devel/spicy/reference.rst

@@ -305,7 +305,7 @@ File analyzers support the following properties:
             "content sniffing" (i.e., similar to libmagic), and
             usually not by protocol-level headers (e.g., *not* through
             HTTP's ``Content-Type`` header). If in doubt, examine
-            ``files.log`` for what it records as a file's type.
+            :file:`files.log` for what it records as a file's type.
 
     ``replaces ANALYZER_NAME``
         Disables an existing file analyzer that Zeek already provides
@@ -942,7 +942,7 @@ membership in a ``set`` like this:
 
 .. code-block:: zeek
 
-   # Zeek module `MyModule`
+   # Zeek module MyModule
    option my_set: set[count] = { 1, 2, 3 };
 
 .. code-block:: spicy
@@ -958,7 +958,7 @@ functions for conversion. Example accessing a record's field:
 
 .. code-block:: zeek
 
-   # Zeek module `MyModule`
+   # Zeek module MyModule
    option my_record: record {
        a: count &default = 42;
        b: string &default = "foo";
@@ -1103,7 +1103,7 @@ see what it's doing at runtime. You'll need a debug version of Zeek
 for that, as well as a small trace with traffic that you expect your
 analyzer to process. Run Zeek with ``-B dpd`` (or ``-B file_analysis``
 if you're debugging a file analyzer) on your trace to record the
-analyzer activity into ``debug.log``. For example, with the same HTTP
+analyzer activity into :file:`debug.log`. For example, with the same HTTP
 example, we get:
 
 .. code-block:: text
@@ -1189,4 +1189,3 @@ their full Zeek-side values::
                   [2] uri: string        = /index.html
                   [3] version: string    = 1.0
     [...]
-

devel/spicy/tutorial.rst

@@ -208,7 +208,7 @@ the corresponding value of ``is_read``. Let's try it with a new
     # zeek -r tftp_rrq.pcap tftp.hlto tftp.zeek
     TFTP read request, [orig_h=192.168.0.253, orig_p=50618/udp, resp_h=192.168.0.10, resp_p=69/udp], T, rfc1350.txt, octet
 
-If we look at the ``conn.log`` that Zeek produces during this run, we
+If we look at the :file:`conn.log` that Zeek produces during this run, we
 will see that the ``service`` field is not filled in yet. That's
 because our analyzer does not yet confirm to Zeek that it has been
 successful in parsing the content. To do that, we can call a library
@@ -333,7 +333,7 @@ analyzers' events, and collect and correlate their activity as
 desired. We have created such :download:`a script for TFTP
 <autogen/tftp.zeek>`, based on the events that our Spicy analyzer
 generates. Once we add that to the Zeek command line, we will see a
-new ``tftp.log``:
+new :file:`tftp.log`:
 
 .. code::
 
@@ -346,7 +346,7 @@ new ``tftp.log``:
 The TFTP script also labels the second session as TFTP data by
 adding a corresponding entry to the ``service`` field inside the
 Zeek-side connection record. With that, we are now seeing this in
-``conn.log``:
+:file:`conn.log`:
 
 .. code::
 

ext/spicy-pygments.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2023 by the Zeek Project. See LICENSE for details.
+# Copyright (c) 2020-now by the Zeek Project. See LICENSE for details.
 
 from pygments.lexer import RegexLexer, bygroups, include, words
 from pygments.token import (

frameworks/file-analysis.rst

@@ -84,12 +84,12 @@ File Type Identification
 Zeek ships with its own library of content signatures to determine the type of a
 file, conveyed as MIME types in the :zeek:see:`file_sniff` event. You can find
 those signatures in the Zeek distribution's ``scripts/base/frameworks/files/magic/``
-directory. (Despite the name, Zeek does `not` rely on libmagic for content analysis.)
+directory. (Despite the name, Zeek does *not* rely on libmagic for content analysis.)
 
 Adding Analysis
 ===============
 
-Zeek supports customized file analysis via `file analyzers` that users can
+Zeek supports customized file analysis via *file analyzers* that users can
 attach to observed files. You can attach analyzers selectively to individual
 files, or register them for auto-attachment under certain conditions. Once
 attached, file analyzers start receiving the contents of files as Zeek parses
@@ -139,7 +139,7 @@ for additional APIs and data structures.
 
 Regardless of which file analyzers end up acting on a file, general
 information about the file (e.g. size, time of last data transferred,
-MIME type, etc.) is logged in ``files.log``.
+MIME type, etc.) is logged in :file:`files.log`.
 
 Protocol-specific state
 -----------------------
@@ -207,8 +207,8 @@ customized analysis. Since observed files can be very large, Zeek cannot buffer
 these files and provide their entire content to the script layer once
 complete. Instead, the ``FileDataEvent`` analyzer reflects the incremental
 nature of file content as Zeek observes it, and supports two types of events to
-allow you to process it: user-provided `stream events` receive new file content
-as supplied by connection-oriented protocols, while `chunk events` receive
+allow you to process it: user-provided *stream events* receive new file content
+as supplied by connection-oriented protocols, while *chunk events* receive
 observed data as provided by protocols that do not feature stream semantics.
 
 The following example manually computes the SHA256 hash of each observed file by

frameworks/input.rst

@@ -318,7 +318,7 @@ Broken input data
 -----------------
 
 The input framework notifies you of problems during data ingestion in two ways.
-First, reporter messages, ending up in reporter.log, indicate the type of
+First, reporter messages, ending up in :file:`reporter.log`, indicate the type of
 problem and the file in which the problem occurred::
 
   #fields ts      level   message location