Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-04 15:48:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Update script doc-generation README.

Browse source 
And remove an unused reference in sphinx source tree index's TOC.
This commit is contained in:
Jon Siwek 2011-08-05 10:39:26 -05:00
parent ca2582d325
commit c2bfe0d78d
2 changed files with 19 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

32
doc/scripts/README
View file

@ -38,20 +38,26 @@ by CMake:
This target removes Sphinx inputs and outputs from the CMake ``build/`` dir. This target removes Sphinx inputs and outputs from the CMake ``build/`` dir.
To schedule a script to be documented, edit ``DocSourcesList.cmake`` inside The ``genDocSourcesList.sh`` script can be run to automatically generate
this directory add a call to the ``rest_target()`` macro. Calling that macro ``DocSourcesList.cmake``, which is the file CMake uses to define the list
with a group name for the script is optional. If the group is omitted, the of documentation targets. This script should be run after adding new
only links to the script will be in the master TOC tree for all policy scripts Bro script source files, and the changes commited to git.
as well as the master TOC tree for script packages (derived from the path
component of the second argument to ``rest_target()``), with the exception
of ``.bif`` files which are grouped automatically.
When adding a new logical grouping e.g. "my/group" (groups are allowed If a script shouldn't have documentation generated for it, there's also a
to contain slashes specifying a path) for generated scripts, blacklist variable that can be maintained in the ``genDocSourcesList.sh``
create a new reST document in ``source/my/group.rst`` and add some default script.
documentation for the group. References to (and summaries of) documents
associated with the group get appended to this pre-created file during the The blacklist can also be used if you want to define a certain grouping for
``make doc`` process. the script's generated docs to belong to (as opposed to the automatic grouping
the happens for script packages/directories). To do that, add the
script's name to the blacklist, then append a ``rest_target()`` to the
``statictext`` variable where the first argument is the source directory
containing the policy script to document, the second argument is the file
name of the policy script, and the third argument is the path/name of a
pre-created reST document in the ``source/`` directory to which the
``make doc`` process can append script documentation references. This
pre-created reST document should also then be linked to from the TOC tree
in ``source/index.rst``.
The Sphinx source tree template in ``source/`` can be modified to add more The Sphinx source tree template in ``source/`` can be modified to add more
common/general documentation, style sheets, JavaScript, etc. The Sphinx common/general documentation, style sheets, JavaScript, etc. The Sphinx

1
doc/scripts/source/index.rst
View file

@ -14,7 +14,6 @@ Contents:
internal internal
bifs bifs
packages packages
collections
policy/index policy/index
Indices and tables Indices and tables