Documentation
=============

This directory contains Bro documentation in reStructuredText format
(see http://docutils.sourceforge.net/rst.html).

It is the root of a Sphinx source tree and can be modified to add more
common/general documentation, style sheets, JavaScript, etc.  The Sphinx
config file is produced from ``conf.py.in``, and can be edited to change
various Sphinx options.

There is also a custom Sphinx domain implemented in ``source/ext/bro.py``
which adds some reST directives and roles that aid in generating useful
index entries and cross-references.  Other extensions can be added in
a similar fashion.

Either the ``make doc`` or ``make broxygen`` targets in the top-level
Makefile can be used to locally render the reST files into HTML.
Those targets depend on:

* Python interpreter >= 2.5
* `Sphinx <http://sphinx.pocoo.org/>`_ >= 1.0.1

After completion, HTML documentation is symlinked in ``build/html``.

There's also ``make docclean`` and ``make broxygenclean`` targets to
clean the resulting documentation.

Notes for Writing Documentation
-------------------------------

* If you want to refer to a document that's part of the
  distribution, it currently needs to be copied or otherwise symlinked
  somewhere in to this Sphinx source tree. Then, it can be referenced
  in a toc tree or with the :doc: role.  Use the :download: role to
  refer to static files that will not undergo sphinx rendering.

* If you want to refer to a page on the Bro web site, use an HTTP URL.

Guidelines
----------

TODO.