Add manual page.

[ckreibich]

This uses the argparse_manpage Python package, which does a reasonably good job at turning the argparse parser into a manpage. The setup is manual (you have to run man/build.py to update the manpage), and installation happens only when bundled with Zeek (like for zkg etc).

Resolves #20.

[bbannier]

Nit: This is needed since the script lives in a subdirectory which is not a submodule of zeekclient. If you moved the file to e.g., the root directory (maybe renamed as build_manpage.py; also requires changing the write below) you would be able to simply use

import zeekclient.cli

This then also wouldn't require suppressing any pylint errors.

[bbannier]

I think the default exception text for ImportError is already pretty useful, and creating a custom one isn't usually needed, especially for tooling intended for developers.

If you added this to work around pylint failing to import this, instead add it to the list of pylint dependencies. Regardless of motivation, you should consider adding the dependency to the pylint pre-commit hook so it can check the code,

- repo: https://github.com/PyCQA/pylint
  rev: v3.0.0a7
  hooks:
  - id: pylint
    additional_dependencies:
      - argparse_manpage
      - websocket-client

[bbannier]

It looks like setting parser.prog in man/build.py is insufficient, not exactly sure how to fix that.

    # The parser currently has this script as program name, so replace:
    parser.prog = "zeek-client"

Here and below.

[ckreibich]

Oh nice — I missed that! I'm fixing it by changing the name in sys.argv, prior to the parser generation.

[bbannier]

The argparse-manpage docs document a way to set up building manpages automatically as part of setup.py. I think that would preferable over having the output in the repo.

If you want to track them in the repo, let's add a pre-commit hook which makes sure that the manpage is up-to-date:

- repo: local
  hooks:
  - id: generate-manpage
    name: Generate manpage
    language: python
    additional_dependencies:
      - argparse_manpage
      - websocket-client
    entry: ./build_manpage.py

[ckreibich]

I don't really want to generate the manpage on the fly because we're not doing that for any of the other manpages in the project either, but I like the idea of tracking whether the current one is outdated. Will do.

[bbannier]

LGTM module my new comment on checking whether the manpage is up-to-date with a pre-commit hook.

[bbannier]

The argparse_manpage module by defaults embeds the time the build job was run into the generated manpage. This probably makes sense, but interferes with running this from a pre-commit hook as the output is not reproducible.

The module supports reproducible builds with SOURCE_DATE_EPOCH. We could set this in build.py before calling Manpage, e.g.,

os.environ['SOURCE_DATE_EPOCH'] = "1694507965"

This is unfortunately pretty opaque and would need a comment.

Git does not preserve mtime, so e.g., the following unfortunately would not work:

os.environ['SOURCE_DATE_EPOCH'] = f"{int(os.path.getmtime(__file__))}"

If you believe this is too much hassle to implement, we should not use this as a pre-commit hook.

[ckreibich]

Thanks! I just removed the date altogether.

[bbannier]

This could arguably be in the default description.