From 0efdee0715421098379128a64096fef75f52ecd1 Mon Sep 17 00:00:00 2001 From: Christian Kreibich Date: Thu, 18 Aug 2022 19:04:02 -0700 Subject: [PATCH 1/3] Add Sphinx label to Zeekygen-generated plugin docs Plugin documentation generated by Zeekygen is currently difficult to reference from elsewhere in the docs because references prefer labels for unique identification. This expands the plugin section headings with a unique label, based on the plugin name. For example, the documentation for a plugin called Zeek::Foobar becomes linkable from anywhere via :ref:`plugin-zeek-foobar`. --- src/zeekygen/Target.cc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/zeekygen/Target.cc b/src/zeekygen/Target.cc index ef5b32d092..5236b8b070 100644 --- a/src/zeekygen/Target.cc +++ b/src/zeekygen/Target.cc @@ -6,6 +6,7 @@ #include #include #include +#include #include "zeek/Reporter.h" #include "zeek/analyzer/Component.h" @@ -28,6 +29,16 @@ static void write_plugin_section_heading(FILE* f, const plugin::Plugin* p) { const string& name = p->Name(); + // A label-safe version of the plugin name: replace _ and : with -, turn + // sequences of - into single ones, and make lower-case. Example: + // "Zeek::IEEE802_11" -> "zeek-ieee802-11". + auto flags = std::regex_constants::match_any; + string label_name = std::regex_replace(name, std::regex("[_:]"), "-", flags); + label_name = std::regex_replace(label_name, std::regex("-+"), "-", flags); + label_name = zeek::util::strtolower(label_name); + + fprintf(f, ".. _plugin-%s:\n\n", label_name.c_str()); + fprintf(f, "%s\n", name.c_str()); for ( size_t i = 0; i < name.size(); ++i ) fprintf(f, "-"); From f1a91081994b2e27ace0b8130f299cc19eecde1b Mon Sep 17 00:00:00 2001 From: Christian Kreibich Date: Fri, 19 Aug 2022 13:14:37 -0700 Subject: [PATCH 2/3] Remove long-unused BRO_DISABLE_BROXYGEN env var from btests --- testing/btest/doc/zeekygen/command_line.zeek | 6 +++--- testing/btest/doc/zeekygen/comment_retrieval_bifs.zeek | 2 +- testing/btest/doc/zeekygen/enums.zeek | 2 +- testing/btest/doc/zeekygen/example.zeek | 2 +- testing/btest/doc/zeekygen/func-params.zeek | 2 +- testing/btest/doc/zeekygen/identifier.zeek | 2 +- testing/btest/doc/zeekygen/package.zeek | 2 +- testing/btest/doc/zeekygen/package_index.zeek | 2 +- testing/btest/doc/zeekygen/records.zeek | 2 +- testing/btest/doc/zeekygen/script_index.zeek | 2 +- testing/btest/doc/zeekygen/script_summary.zeek | 2 +- testing/btest/doc/zeekygen/type-aliases.zeek | 2 +- testing/btest/doc/zeekygen/vectors.zeek | 2 +- 13 files changed, 15 insertions(+), 15 deletions(-) diff --git a/testing/btest/doc/zeekygen/command_line.zeek b/testing/btest/doc/zeekygen/command_line.zeek index f13e43f300..3d3ba8ccef 100644 --- a/testing/btest/doc/zeekygen/command_line.zeek +++ b/testing/btest/doc/zeekygen/command_line.zeek @@ -4,9 +4,9 @@ # Shouldn't emit any warnings about not being able to document something # that's supplied via command line script. -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek %INPUT -e 'redef myvar=10; print myvar' >output 2>&1 -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -e '@load %INPUT print myvar' >>output 2>&1 -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek %INPUT -e 'module mymodule; print myvar' >>output 2>&1 +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek %INPUT -e 'redef myvar=10; print myvar' >output 2>&1 +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -e '@load %INPUT print myvar' >>output 2>&1 +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek %INPUT -e 'module mymodule; print myvar' >>output 2>&1 # @TEST-EXEC: btest-diff output const myvar = 5 &redef; diff --git a/testing/btest/doc/zeekygen/comment_retrieval_bifs.zeek b/testing/btest/doc/zeekygen/comment_retrieval_bifs.zeek index 8594aa2195..b93e522c24 100644 --- a/testing/btest/doc/zeekygen/comment_retrieval_bifs.zeek +++ b/testing/btest/doc/zeekygen/comment_retrieval_bifs.zeek @@ -1,4 +1,4 @@ -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b %INPUT >out +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b %INPUT >out # @TEST-EXEC: btest-diff out ##! This is a test script. diff --git a/testing/btest/doc/zeekygen/enums.zeek b/testing/btest/doc/zeekygen/enums.zeek index 3e44a037be..0a2ec645e4 100644 --- a/testing/btest/doc/zeekygen/enums.zeek +++ b/testing/btest/doc/zeekygen/enums.zeek @@ -1,4 +1,4 @@ -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT # @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-enums.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/example.zeek b/testing/btest/doc/zeekygen/example.zeek index 220de0be51..7956eaf7a6 100644 --- a/testing/btest/doc/zeekygen/example.zeek +++ b/testing/btest/doc/zeekygen/example.zeek @@ -1,4 +1,4 @@ -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT # @TEST-EXEC: btest-diff example.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/func-params.zeek b/testing/btest/doc/zeekygen/func-params.zeek index 8b590e8168..ff87ca4d32 100644 --- a/testing/btest/doc/zeekygen/func-params.zeek +++ b/testing/btest/doc/zeekygen/func-params.zeek @@ -1,4 +1,4 @@ -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT # @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-func-params.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/identifier.zeek b/testing/btest/doc/zeekygen/identifier.zeek index 6763c5c223..1615921514 100644 --- a/testing/btest/doc/zeekygen/identifier.zeek +++ b/testing/btest/doc/zeekygen/identifier.zeek @@ -1,5 +1,5 @@ # @TEST-PORT: BROKER_PORT -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT # @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff test.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/package.zeek b/testing/btest/doc/zeekygen/package.zeek index a2c66f2c91..eb0f062866 100644 --- a/testing/btest/doc/zeekygen/package.zeek +++ b/testing/btest/doc/zeekygen/package.zeek @@ -1,5 +1,5 @@ # @TEST-PORT: BROKER_PORT -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT # @TEST-EXEC: btest-diff test.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/package_index.zeek b/testing/btest/doc/zeekygen/package_index.zeek index 7831ea25ee..3c89d9439f 100644 --- a/testing/btest/doc/zeekygen/package_index.zeek +++ b/testing/btest/doc/zeekygen/package_index.zeek @@ -1,5 +1,5 @@ # @TEST-PORT: BROKER_PORT -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT # @TEST-EXEC: btest-diff test.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/records.zeek b/testing/btest/doc/zeekygen/records.zeek index dc0cd7f69b..49993385de 100644 --- a/testing/btest/doc/zeekygen/records.zeek +++ b/testing/btest/doc/zeekygen/records.zeek @@ -1,4 +1,4 @@ -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT # @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-records.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/script_index.zeek b/testing/btest/doc/zeekygen/script_index.zeek index a58d82c1d9..08c11239a5 100644 --- a/testing/btest/doc/zeekygen/script_index.zeek +++ b/testing/btest/doc/zeekygen/script_index.zeek @@ -1,5 +1,5 @@ # @TEST-PORT: BROKER_PORT -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT # @TEST-EXEC: btest-diff test.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/script_summary.zeek b/testing/btest/doc/zeekygen/script_summary.zeek index 8eb5785cae..f696410512 100644 --- a/testing/btest/doc/zeekygen/script_summary.zeek +++ b/testing/btest/doc/zeekygen/script_summary.zeek @@ -1,5 +1,5 @@ # @TEST-PORT: BROKER_PORT -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT Broker::default_port=$BROKER_PORT # @TEST-EXEC: btest-diff test.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/type-aliases.zeek b/testing/btest/doc/zeekygen/type-aliases.zeek index 26f875ff61..a71b37504a 100644 --- a/testing/btest/doc/zeekygen/type-aliases.zeek +++ b/testing/btest/doc/zeekygen/type-aliases.zeek @@ -1,4 +1,4 @@ -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT # @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-type-aliases.rst @TEST-START-FILE zeekygen.config diff --git a/testing/btest/doc/zeekygen/vectors.zeek b/testing/btest/doc/zeekygen/vectors.zeek index d249149662..5862888fdc 100644 --- a/testing/btest/doc/zeekygen/vectors.zeek +++ b/testing/btest/doc/zeekygen/vectors.zeek @@ -1,4 +1,4 @@ -# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; unset BRO_DISABLE_BROXYGEN; zeek -b -X zeekygen.config %INPUT +# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN; zeek -b -X zeekygen.config %INPUT # @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff autogen-reST-vectors.rst @TEST-START-FILE zeekygen.config From 17a140b67a95a96d04600cd4141d63dbf938c8b0 Mon Sep 17 00:00:00 2001 From: Christian Kreibich Date: Fri, 19 Aug 2022 17:19:30 -0700 Subject: [PATCH 3/3] Bump doc to pull in Sphinx exclusion for autogenerated files --- doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc b/doc index 8842cd14a1..69d16be3c6 160000 --- a/doc +++ b/doc @@ -1 +1 @@ -Subproject commit 8842cd14a1e02941f87e73f2f7860211a123b4a0 +Subproject commit 69d16be3c603b3c20ebfe4d3c943d8e27bb7e00c