6. Developer’s Guide

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

6.1. Versioning/Releases

After making a commit to the master branch, you can use the update-changes script in the bro-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:

  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 ‘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 minimal requirements in requirements.doc.txt:

Sphinx
sphinxcontrib-napoleon
GitPython
semantic_version
configparser
sphinx_rtd_theme

They can be installed like:

pip install -r requirements.doc.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.