6. Developer's Guide

This a guide for developers working on the Zeek Package Manager itself.

6.1. Versioning/Releases

After making a commit to the master branch, you can use the update-changes script in the zeek-aux repository to automatically adapt version numbers and regenerate the zkg man page. Make sure to install the documentation dependencies before using it.

Releases are hosted at PyPi. To build and upload a release:

  1. Finalize the git repo tag and version with update-changes -R <version> if not done already.

  2. Upload the distribution (you will need the credentials for the 'zeek' account on PyPi):

    $ make upload
    

6.2. Documentation

Documentation is written in reStructuredText (reST), which Sphinx uses to generate HTML documentation and a man page.

6.2.1. Dependencies

To build documentation locally, find the requirements in requirements.txt:

# Requirements for general zkg usage
GitPython
semantic_version
configparser
btest
# Requirements for development (e.g. building docs)
Sphinx
sphinxcontrib-napoleon
sphinx_rtd_theme

They can be installed like:

pip install -r requirements.txt

6.2.2. Local Build/Preview

Use the Makefile targets make html and make man to build the HTML and man page, respectively. To view the generated HTML output, open doc/_build/index.html. The generated man page is located in doc/man/zkg.1.

If you have also installed sphinx-autobuild (e.g. via pip), there's a Makefile target, make livehtml, you can use to help preview documentation changes as you edit the reST files.

6.2.3. Remote Hosting

The GitHub repository has a webhook configured to automatically rebuild the HTML documentation hosted at Read the Docs whenever a commit is pushed.

6.2.4. Style Conventions

The following style conventions are (generally) used.

Documentation Subject reST Markup Preview
File Path :file:`path` path
File Path w/ Substitution :file:`{<replace_me>}/path` <replace_me>/path
OS-Level Commands :command:`cmd` cmd
Program Names :program:`prog` prog
Environment Variables :envvar:`VAR` VAR
Literal Text (e.g. code) ``code`` code
Substituted Literal Text :samp:`code {<replace_me>}` code <replace_me>
Variable/Type Name `x` x
INI File Option `name` name

Python API docstrings roughly follow the Google Style Docstrings format.