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 w/ Substitution |
|
|
OS-Level Commands |
|
cmd |
Program Names |
|
prog |
Environment Variables |
|
|
Literal Text (e.g. code) |
|
|
Substituted Literal Text |
|
|
Variable/Type Name |
|
x |
INI File Option |
|
name |
Python API docstrings roughly follow the Google Style Docstrings format.