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:

Finalize the git repo tag and version with update-changes -R <version> if not done already.
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
btest
# Requirements for development (e.g. building docs)
Sphinx>=3.0
sphinx_rtd_theme

They can be installed like:

pip3 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, or make doc to build them both. 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 pip3), 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.