zeek/doc
Robin Sommer ac66db286a Merge remote-tracking branch 'origin/topic/documentation'
I'm merging in the documentation branch to avoid that it keeps getting
out of sync. We still need to work on this a bit more, I'll summarize
in a mail.

* origin/topic/documentation: (68 commits)
  Going over initial parts of the scripting overview.
  Adding lines in scripting/index.txt. No other change.
  Updating submodule.
  Pass over the Using Bro section.
  Applying doc updates from BIT-1063. (Anthony Verez)
  Breaking lines in using/*.
  More doc reorg, and a light pass over the first 3 sections.
  Starting to put a new structure in place.
  Updating submodule(s).
  Updating submodule(s).
  Adding some temporary testing/demonstration to front page.
  Switching btest to topic/robin/parts branch.
  Basic cross-referencing UIDs between files, btests, and baselines.
  A truly embarassing number of spelling corrections.
  Using redirection with bro-cut.  Include initial btests for this document.
  Corrected a mis-typed RST include.
  Initial start for "Using Bro".
  Spelling corrections.
  Include Notice Policy shortcuts in the Scripting User Manual.
  Notice::policy hooks and tests.
  ...

Conflicts:
	src/3rdparty
2013-08-31 16:07:44 -07:00
..
_static Tweaks. 2012-01-09 18:28:43 -08:00
_templates s/bro-ids.org/bro.org/g 2013-03-07 19:33:04 -08:00
bin Changed make doc target to re-use Sphinx cache. 2012-10-24 17:04:44 -05:00
cluster Restructuring the main documentation index. 2013-04-01 17:30:12 -07:00
components Merge remote-tracking branch 'origin/topic/documentation' 2013-08-31 16:07:44 -07:00
ext Going over initial parts of the scripting overview. 2013-08-30 16:23:17 -07:00
frameworks Pass over the Using Bro section. 2013-08-22 16:04:45 -07:00
images Adapt more www niceties to broxygen (stylesheets, pygments); add more docs 2011-11-15 15:39:31 -06:00
install Merge remote-tracking branch 'origin/topic/documentation' 2013-08-31 16:07:44 -07:00
intro More doc reorg, and a light pass over the first 3 sections. 2013-08-19 22:08:30 -07:00
quickstart Going over initial parts of the scripting overview. 2013-08-30 16:23:17 -07:00
scripting Going over initial parts of the scripting overview. 2013-08-30 16:23:17 -07:00
scripts Merge remote-tracking branch 'origin/topic/documentation' 2013-08-31 16:07:44 -07:00
using Going over initial parts of the scripting overview. 2013-08-30 16:23:17 -07:00
.gitignore A set of script-reference polishing. 2012-01-09 18:04:34 -08:00
CMakeLists.txt Restructuring the main documentation index. 2013-04-01 17:30:12 -07:00
conf.py.in Merge remote-tracking branch 'origin/topic/documentation' 2013-08-31 16:07:44 -07:00
index.rst Merge remote-tracking branch 'origin/topic/documentation' 2013-08-31 16:07:44 -07:00
LICENSE New branch for documentation, with an initial skeleton. 2012-10-24 11:13:02 -07:00
README corrected some minor typos 2012-01-11 13:02:12 -06:00

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.