mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
9967aea52c
Add a "broxygen" domain Sphinx extension w/ directives to allow on-the-fly documentation to be generated w/ Bro and included in files. This means all autogenerated reST docs are now done by Bro. The odd CMake/Python glue scipts which used to generate some portions are now gone. Bro and the Sphinx extension handle checking for outdated docs themselves. Parallel builds of `make doc` target should now work (mostly because I don't think there's any tasks that can be done in parallel anymore). Overall, this seems to simplify things and make the Broxygen-generated portions of the documentation visible/traceable from the main Sphinx source tree. The one odd thing still is that per-script documentation is rsync'd in to a shadow copy of the Sphinx source tree within the build dir. This is less elegant than using the new broxygen extension to make per-script docs, but rsync is faster and simpler. Simpler as in less code because it seems like, in the best case, I'd need to write a custom Sphinx Builder to be able to get that to even work.
46 lines
1.5 KiB
Text
46 lines
1.5 KiB
Text
|
|
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.
|
|
|
|
The ``make doc`` target in the top-level Makefile can be used to locally
|
|
render the reST files into HTML. That target 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 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.
|
|
|
|
|
|
|