{"id":28644582,"url":"https://github.com/zeek/zeek-docs","last_synced_at":"2025-06-13T00:08:56.682Z","repository":{"id":37258509,"uuid":"166280120","full_name":"zeek/zeek-docs","owner":"zeek","description":"Documentation for Zeek","archived":false,"fork":false,"pushed_at":"2025-06-12T00:26:21.000Z","size":80588,"stargazers_count":50,"open_issues_count":28,"forks_count":69,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-06-12T01:31:10.028Z","etag":null,"topics":["bro","dfir","network-monitoring","nsm","pcap","security","zeek"],"latest_commit_sha":null,"homepage":"https://docs.zeek.org","language":"Zeek","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zeek.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-01-17T19:02:22.000Z","updated_at":"2025-06-12T00:26:24.000Z","dependencies_parsed_at":"2023-10-27T19:31:01.637Z","dependency_job_id":"4b2bfa55-a96e-4c53-82ac-34c3ed053240","html_url":"https://github.com/zeek/zeek-docs","commit_stats":null,"previous_names":[],"tags_count":154,"template":false,"template_full_name":null,"purl":"pkg:github/zeek/zeek-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeek%2Fzeek-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeek%2Fzeek-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeek%2Fzeek-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeek%2Fzeek-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zeek","download_url":"https://codeload.github.com/zeek/zeek-docs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeek%2Fzeek-docs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259553130,"owners_count":22875611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bro","dfir","network-monitoring","nsm","pcap","security","zeek"],"created_at":"2025-06-13T00:08:51.877Z","updated_at":"2025-06-13T00:08:56.642Z","avatar_url":"https://github.com/zeek.png","language":"Zeek","funding_links":[],"categories":[],"sub_categories":[],"readme":".. _zeek-docs: https://github.com/zeek/zeek-docs\n.. _Read the Docs: https://docs.readthedocs.io/en/stable/index.html\n.. _Zeek repo: https://github.com/zeek/zeek\n.. _Sphinx: https://www.sphinx-doc.org/en/master\n.. _pip: https://pypi.org/project/pip\n\nZeek Documentation\n==================\n\nThe documentation repo at zeek-docs_\ncontains version-specific Zeek documentation source files that are ultimately\nused as the basis for content hosted at https://docs.zeek.org.\n\nMarkup Format, Style, and Conventions\n-------------------------------------\n\nFor general guidance on the basics of how the documentation is written,\nconsult this Zeek wiki:\n\nhttps://github.com/zeek/zeek/wiki/Documentation-Style-and-Conventions\n\nSource-Tree Organization\n------------------------\n\nThe zeek-docs_ repo containing this README file is the root of a Sphinx_ source\ntree and can be modified to add more documentation, style sheets, JavaScript,\netc.  The Sphinx config file is ``conf.py``.  The typical way new documents get\nintegrated is from them being referenced directly in ``index.rst`` or\nindirectly from something in the ``toctree`` (Table of Contents Tree) specified\nin that main index.\n\nThere is also a custom Sphinx domain implemented in ``ext/zeek.py`` which adds\nsome reStructureText (reST) directives and roles that aid in generating useful\nindex entries and cross-references. This primarily supports integration with\nthe script-reference sections, some of which are auto-generated by Zeek's\nDoxygen-like feature, named \"Zeekygen\".  The bulk of auto-generated content\nlives under the ``scripts/`` directory or has a file name starting with\n\"autogenerated\", so if you find yourself wanting to change those, you should\nactually look at at doing those changes within the `Zeek repo`_ itself rather\nthan here, so see the next section for how Zeekygen docs can be (re)generated.\n\nGenerating Zeekygen Reference Docs\n----------------------------------\n\nAll Zeekygen-generated docs get committed into Git, so if you don't have to\nperform any changes on it and just want to preview what's already existing,\nyou can skip down to the next :ref:`Local Previewing \u003clocal-doc-preview\u003e` section.\n\nThe Zeekygen documentation-generation feature is a part of Zeek itself, so\nyou'll want to obtain the `Zeek repo`_ from Git, read the :doc:`INSTALL\n\u003c/install\u003e` file directions to install required dependencies, and build Zeek::\n\n  git clone --recursive https://github.com/zeek/zeek\n  cd zeek\n  # Read INSTALL file and get dependencies here\n  ./configure \u0026\u0026 make -j $(nproc)\n  # Make desired edits to scripts/, src/, etc.\n  ./ci/update-zeekygen-docs.sh\n\nThe last command runs a script to generate documentation, which will end up in\nthe ``doc/`` subdirectory.  Note that ``doc/`` is just a Git submodule of this\nthis zeek-docs_ repository, so you can run ``git status`` there to find exactly\nwhat changed.\n\nAlso note that the documentation-generation script is run automatically\non a daily basis to incorporate up any documentation changes that people make\nin Zeek itself without them having to necessarily be aware of the full\ndocumentation process.  The GitHub Action that does that daily task is\nlocated in the Zeek repo's ``.github/workflows/generate-docs.yml`` file.\n\n.. _local-doc-preview:\n\nLocal Previewing (How To Build)\n-------------------------------\n\nFirst make sure you have the required dependencies used for building docs:\n\n* Python interpreter \u003e= 3.9\n* Sphinx: https://www.sphinx-doc.org/en/master/\n* Read the Docs Sphinx Theme: https://github.com/rtfd/sphinx_rtd_theme\n* GitPython: https://github.com/gitpython-developers/GitPython\n\nIf you have pip_, you may just use the command ``pip3 install -r\nrequirements.txt`` to install all the dependencies using the\n``requirements.txt`` from zeek-docs_.\n\nNow run ``make`` within the zeek-docs_ repository's top-level to locally render\nits reST files into HTML. After the build completes, HTML documentation is\nsymlinked in ``build/html`` and you can open the ``index.html`` found there in\nyour web browser.\n\nThere's also a ``make livehtml`` (requires ``pip3 install sphinx-autobuild``)\ntarget in the top-level Makefile that is useful for editing the reST files and\nseeing changes rendered out live to a separate browser.\n\nHosting\n-------\n\nDocumentation is hosted by `Read the Docs`_ (RTD), so you can generally read\nabout how it works there.  The web-interface is accessible via\nhttps://readthedocs.org/projects/zeek-docs.\n\nHow zeek-docs_ is configured to use RTD is a combination of some custom\nsettings in its ``.readthedocs.yml`` file and others only accessible through\nRTD's web-interface (e.g. domain and subproject settings).  Most config\nsettings are likely understandable just by browsing the web-interface and\nRTD's guides, but a few particular points to mention:\n\n* There is an associated, always-failing project at\n  https://readthedocs.org/projects/zeek.  It's always-failing because\n  RTD redirects only activate when pages 404 and this project exists so that\n  all attempts to use https://zeek.rtfd.io or https://zeek.readthedocs.io\n  get redirected to https://docs.zeek.org.  Those would have been the project\n  URLs if ownership of the RTD 'zeek' project was had from the start, but\n  it was only obtained later, after documentation already started development\n  in the 'zeek-docs' RTD project slug.\n\n* Over time, page redirects have accrued into ``redirects.yml`` as a way to\n  help document what they are and why they happened and also as a potential\n  way to automate addition/reinstantiation of a large number of redirects,\n  but typically redirects can be manually added via the RTD web interface\n  first and then noted in ``redirects.yml``\n\n* There are RTD subprojects for things like Broker, Package Manager,\n  and Spicy.  The use of subprojects simply allows access to their RTD\n  docs via the custom domain of https://docs.zeek.org\n\n* RTD will auto-build any newly-pushed commits to zeek-docs_ (i.e. a webhook is\n  configured), but if a tag is changed to point somewhere different, you'll\n  typically have to go into the RTD web interface, \"Edit\" the associated\n  version under \"Versions\", \"wipe\" the existing docs, and then manually trigger\n  a rebuild of that version tag under \"Builds\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeek%2Fzeek-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeek%2Fzeek-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeek%2Fzeek-docs/lists"}