On Tue, Aug 25, 2020 at 3:27 AM Jan Grashöfer <jan.grashoe...@gmail.com>
wrote:
>
> I like that idea! It would be great to have a standard process for
> generating docs for each package.
>
I've been working[1] on a template for Zeek packages that consist only of
scripts. It's based heavily on the plugin-support[2] in zeek-aux, but it
goes a few steps further by running the tests via GitHub Actions with the
current {zeek, zeek-lts, zeek-nightly} packages. It also integrates with
GitHub Pages to auto-generate the Sphinx documentation. You can see an
example here: https://grigorescu.github.io/external_dns/. (Note: This is my
"working" package, and deviates from the upstream cookiecutter as I play
around with new things).
It tries to combine the user-provided README, with autogenerated
documentation, and some useful things that I bundled into the docs (for
example, explaining how plugins get loaded). One neat feature is using
intersphinx to link to the official Zeek docs, so that all the references
to types, enums, base scripts will still be clickable links.
There are a couple of open questions with this. For instance, Zeekygen does
not generate documentation for redefs within the script that's doing the
redefs. So this[3] will tell you that your script is adding some new notice
types, but the documentation is missing. Also, I don't have a good way to
generate documentation for all your packages into a single page, which
would be nice. I also made some changes to the Sphinx scripts in zeek-docs
that I should probably figure out how to upstream. We might want to just
publish the Sphinx module separately, so that people can just use it.
--Vlad
[1] - <https://github.com/esnet/cookiecutter-zeekpackage>
[2] - <https://github.com/zeek/zeek-aux/tree/master/plugin-support>
[3] - <
https://grigorescu.github.io/external_dns/scripts/NCSA/external_dns/main.zeek.html#redefinitions
>
_______________________________________________
zeek-dev mailing list -- zeek-dev@lists.zeek.org
To unsubscribe send an email to zeek-dev-le...@lists.zeek.org
