This is the documentation for Zeek, hosted at https://docs.zeek.org.

Zeek's documentation is a Read the Docs Sphinx project, found at rtd-docs.

Zeek's documentation style guide can be found here.

The documentation has a top-level conf.py file for any Sphinx configuration. Add documentation by adding a new file, then referencing it within a toctree (or Table of Contents Tree).

Zeek's documentation uses a custom domain from ext/zeek.py. This adds some reStructuredText (reST) directives like :zeek:see: which are used throughout. This is primarily when linking to Zeek's auto-generated documentation via Zeekygen. This auto-generated documentation mostly lives under the scripts/ directory, or its file name starts with "autogenerated." Changes to any auto-generated documentation should go in the corresponding file in the parent Zeek directory. For example, in order to edit documentation from scripts/base/init-bare.zeek.rst, you should edit the file ../scripts/base/init-bare.zeek (relative from the doc directory).

Zeekygen docs are generated from the top-level Zeek directory. You must build Zeek from source first, so read through the building from scratch section to build Zeek. Then, run Zeek's update-zeekygen-docs.sh:

../ci/update-zeekygen-docs.sh

Now, you can preview the changes to make sure they are okay.

First make sure you have the required dependencies used for building docs:

• Python interpreter >= 3.10
• Sphinx: https://www.sphinx-doc.org/en/master/
• Read the Docs Sphinx Theme: https://github.com/readthedocs/sphinx_rtd_theme
• GitPython: https://github.com/gitpython-developers/GitPython

If you have pip, you may just use the command pip3 install -r requirements.txt to install all the dependencies using the requirements.txt.

Now run make within this directory. After the build completes, HTML documentation is symlinked in build/html and you can open the index.html found there in your web browser.

There's also a make livehtml (requires pip3 install sphinx-autobuild) target in the top-level Makefile that is useful for editing the reST files and seeing changes rendered out live to a separate browser.

Documentation is hosted by Read the Docs (RTD). The web-interface is accessible via the zeek-docs project.

The zeek-docs project uses a combination of .readthedocs.yml files (found in ../.readthedocs.yml, for example) and other settings only accessible through the web interface (like domain and subproject settings). Some caveats:

• There is an associated, always-failing project at https://app.readthedocs.org/projects/zeek/. It's always-failing because RTD redirects only activate when pages 404 and this project exists so that all attempts to use https://zeek.rtfd.io or https://zeek.readthedocs.io get redirected to https://docs.zeek.org. Those would have been the project URLs if ownership of the RTD 'zeek' project was had from the start, but it was only obtained later, after documentation already started development in the 'zeek-docs' RTD project slug.
• Redirects are managed via an external script, found in the zeek-aux repository, called doc-redirects. See the output from that script for information on how to use it. Redirects are managed in the redirects.yml file within the doc directory.
• There are RTD subprojects for things like Broker, Package Manager, and Spicy. The use of subprojects simply allows access to their RTD docs via the custom domain of https://docs.zeek.org.
• RTD will auto-build any newly-pushed commits to zeek-docs (i.e., a webhook is configured), but if a tag is changed to point somewhere different, you'll typically have to go into the RTD web interface, "Edit" the associated version under "Versions", "wipe" the existing docs, and then manually trigger a rebuild of that version tag under "Builds".