# Zeek Documentation

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

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

Zeek's documentation style guide can be found [here](https://github.com/zeek/zeek/wiki/Documentation-Style-and-Conventions).

## Source-Tree Organization

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).

## Generating Zeekygen Reference Docs

Zeekygen docs are generated from the top-level Zeek directory. You must build Zeek from source first, so read through [the building from scratch](https://docs.zeek.org/en/current/building-from-source.html) section to build Zeek. Then, run Zeek's `update-zeekygen-docs.sh`:

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

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

> [!NOTE]
> Zeek automatically generates this documentation (via `../.github/workflows/generate-docs.yml`), so it often is not necessary to commit the changed files. Depending on your configuration, the generated files may differ (particularly, AF_Packet will not generate on MacOS).

## Building the Documentation

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

  * **Python interpreter** \>= 3.10
  * **Sphinx**: [https://www.sphinx-doc.org/en/master/](https://www.sphinx-doc.org/en/master/)
  * **Read the Docs Sphinx Theme**: [https://github.com/readthedocs/sphinx\_rtd\_theme](https://github.com/readthedocs/sphinx_rtd_theme)
  * **GitPython**: [https://github.com/gitpython-developers/GitPython](https://github.com/gitpython-developers/GitPython)

If you have [pip][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.

## Hosting

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

The [zeek-docs][rtd-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/](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][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][rtd-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".

[rtd-docs]: https://app.readthedocs.org/projects/zeek-docs
[sphinx]: https://www.sphinx-doc.org/en/master
[zeek repo]: https://github.com/zeek/zeek
[pip]: https://pypi.org/project/pip
[read the docs]: https://docs.readthedocs.com/platform/stable/index.html
[zeek-aux]: https://github.com/zeek/zeek-aux/tree/master
