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 bro-pkg 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 'bro' 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 bro-pkg 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/bro-pkg.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.