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

The ``make doc`` target in the top-level Makefile can be used to locally
render the reST files into HTML.  That target depends on:

* Python interpreter >= 2.5
* `Sphinx <http://sphinx-doc.org/>`_ >= 1.0.1
* Doxygen (required only for building the Broccoli API doc)

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

There's also a ``make docclean`` target which deletes any files
created during the documentation build process.

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.