Documentation Style and Conventions

Overview

Documentation that's closely related to particular Zeek versions (e.g. master vs. LTS) is hosted by Read the Docs at https://docs.zeek.org.

It's derived from the source files located in https://github.com/zeek/zeek-docs. Generally, reStructuredText is the markup syntax used for this documentation. Some source files are automatically generated by extracting information from comments in Zeek scripts. This extraction process is called "Zeekygen" and uses zeek itself to parse scripts as input and produces reStructuredText files as output.

Ultimately, the reStructuredText source tree is processed by Sphinx to produce the final HTML output. It also has its own useful reStructuredText Primer for reference.

For a more detailed description of the general documentation structure, organization, and process see the zeek-docs README file (also available in HTML form)

General reStructuredText/Sphinx Guidelines

• Generally, entities that refer to code or code-like constructs that you want to keep inline with the documentation should be surrounded with double backticks to form an "inline literal" (e.g. ``this``). If there's a more specific convention mentioned below that applies to a particular scenario, use the style it advocates instead.

• Use :samp: for code-like examples that have variable content. Documentation.

• Use :program: to refer to executable programs. Documentation.

• Use :envvar: to refer to environment variables. Documentation.

• Use :file: to refer to a path, directory, or filename. Documentation.

• Use :rfc: to refer to an RFC. Documentation.

• Use cross-referencing :zeek: roles to link to Zeek scripting entities (identifiers, types, enums, keywords, directives, etc.). See Zeekygen Guidelines below.

• Use .. code-block:: {language} instead of literal blocks or inline literals to allow for syntax-highlighting of longer code blocks whenever possible. Documentation

  • For Zeek scripts use zeek as the language.

  • For shell code/examples use console as the language.

  • Note that sourcecode is an alias for code-block so prefer using the later.

• When linking to documents inside the same source tree, prefer to use :doc: rather than link to a full URL since the former is more resilient to re-organizations and domain changes (building the docs will emit a warning if the target document can't be located while a full URL won't and instead 404s until someone notices/fixes). Documentation.

• When linking to sections, prefer using :ref: with an explicit label rather than standard reStructureText link as demonstrated in the Documentation. The reason is similar to what's mentioned there: it's easier to maintain since Sphinx emits warnings if links ever get broken due to a change in a section's name/title.

• Use other reStructuredText or Sphinx markup as you find applicable/useful.

Zeekygen Guidelines

Any Zeek script comment that uses ## (two number-sign/hash symbols) will associate its contents with the subsequent identifier. The contents of the comment can be any arbitrary reStructuredText markup including Sphinx-specific directives/roles.

You can find an example Zeek script using such a comment style with further explanations here: https://github.com/zeek/zeek/blob/master/scripts/zeekygen/example.zeek

The associated reStructuredText that is produced from that Zeek script is here: https://raw.githubusercontent.com/zeek/zeek-docs/master/scripts/zeekygen/example.zeek.rst

The final HTML output rendered by Sphinx is here: https://docs.zeek.org/en/master/scripts/zeekygen/example.zeek.html

Further tips:

• Most every identifier or keyword from the Zeek scripting language can be referred to like :zeek:see:`foo` to generate a cross-referencing hyperlink to foo (for any foo that's a keyword or other user-defined identifier).

  • There are also more specific roles that may also be used, but it's generally not useful to do so unless you find it helps readability of the raw source text:

    • :zeek:id: (any Zeek identifier that's not also a type or enum)
    • :zeek:type: (any Zeek type that's not also an enum)
    • :zeek:enum: (any Zeek enum type)
    • :zeek:attr: (any Zeek attribute)
    • :zeek:namespace: (any Zeek namespace declared via module)

• Any identifier that's an export from a module (namespace) or declared at top-level scope (GLOBAL) gets automatically documented as part of the script's public API whether is has any associated Zeekygen-comments or not, but it's preferable to have them.

• To reference the Zeekygen-generated documentation for a particular script, the :doc: role markup can be used like normal. Here's an example:

  ## This renders a link (in the summary section) to the documentation for
  ## base/protocols/conn/main.zeek
  ## :doc:`/scripts/base/protocols/conn/main.zeek`
  ##
  ## This would render a link to an index of all the script docs within the
  ## base/protocols/conn/ directory:
  ## :doc:`/scripts/base/protocols/conn/index`
  

• When Sphinx complains with a WARNING: Inline emphasis start-string without end-string, check the corresponding source comment for occurrence of a bare special character (e.g. *, _, |, or `). Note that the character may be anywhere in the text paragraph, and need not be on the line that Sphinx complained about! Escaping by saying e.g. \* instead should fix the warning.

• When Sphinx complains with a WARNING: search index couldn't be loaded, but not all documents will be built: the index will be incomplete., then remove the build directory in your zeek-doc clone and start fresh.