Move stuff related to policy script documentation from doc/ to doc/scripts/

doc/CMakeLists.txt

@@ -1,42 +1 @@
-set(POLICY_SRC_DIR ${PROJECT_SOURCE_DIR}/policy)
+add_subdirectory(scripts)
-set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/out)
-set(DOC_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/source)
-set(DOC_SOURCE_WORKDIR ${CMAKE_CURRENT_BINARY_DIR}/source)
-
-file(GLOB_RECURSE DOC_SOURCES FOLLOW_SYMLINKS "*")
-
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
-               ${CMAKE_CURRENT_BINARY_DIR}/conf.py
-               @ONLY)
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate_reST_docs.py.in
-               ${CMAKE_CURRENT_BINARY_DIR}/generate_reST_docs.py
-               @ONLY)
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/scripts/BroToReST.py.in
-               ${CMAKE_CURRENT_BINARY_DIR}/BroToReST.py
-               @ONLY)
-
-add_custom_target(doc
-                  COMMAND "${CMAKE_COMMAND}" -E copy_directory
-                          ${DOC_SOURCE_DIR}
-                          ${DOC_SOURCE_WORKDIR}
-                  COMMAND python generate_reST_docs.py
-                  COMMAND sphinx-build
-                          -b html
-                          -c ${CMAKE_CURRENT_BINARY_DIR}
-                          -d ${DOC_OUTPUT_DIR}/doctrees
-                          ${DOC_SOURCE_WORKDIR}
-                          ${DOC_OUTPUT_DIR}/html
-                  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-                  COMMENT "[Sphinx] Generating Script Documentation"
-                  VERBATIM
-                  # SOURCES just adds stuff to IDE projects as a convienience
-                  SOURCES ${DOC_SOURCES})
-
-add_dependencies(doc bro doc-clean)
-
-add_custom_target(doc-clean
-                  COMMAND "${CMAKE_COMMAND}" -E remove_directory
-                          ${CMAKE_CURRENT_BINARY_DIR}/source
-                  COMMAND "${CMAKE_COMMAND}" -E remove_directory
-                          ${DOC_OUTPUT_DIR}
-                  VERBATIM)

doc/README

@@ -1,44 +1 @@
-This directory contains scripts and templates that can be used to automate
+TODO
-the generation of Bro script documentation.  Two build targets are defined
-by CMake:
-
-``make doc``
-
-    This target depends on a Python interpreter (>=2.5) and
-    `Sphinx <http://sphinx.pocoo.org/>`_ being installed.  Sphinx can be
-    installed like::
-
-        > sudo easy_install sphinx
-
-    This target will also first build the bro binary if it is not already
-    since the generation of reStructuredText (reST) documentation from
-    Bro scripts is integrated within the parsing process.
-
-    After completion, HTML documentation can be located inside the CMake
-    ``build/`` directory as ``build/doc/out/html``.  The generated reST
-    documentation will be located in ``build/doc/source/policy``.
-
-``make doc-clean``
-
-    This target removes Sphinx inputs and outputs from the CMake ``build/`` dir.
-
-To schedule a script to be documented, edit ``scripts/generate_reST_docs.py.in``
-and try adding the name of the script along with an optional script group to
-the ``docs`` dictionary.  That python script also shows other, more specialized
-methods for generating documentation for some types of corner-cases.
-
-When adding a new logical grouping for generated scripts, create a new
-reST document in ``source/policy/<group_name>.rst`` and add some default
-documentation.  References to (and summaries of) documents associated with
-the group get appended to this file during the ``make doc`` process.
-
-The Sphinx source tree template in ``source/`` can be modified to add more
-common/general documentation, style sheets, JavaScript, etc.  The Sphinx
-config file is produced from ``conf.py.in``, so that can be edited to change
-various Sphinx options, like setting the default HTML rendering theme.
-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.
-
-See ``example.bro`` for an example of how to document a Bro script such that
-``make doc`` will be able to produce reST/HTML documentation for it.

doc/scripts/CMakeLists.txt

@@ -0,0 +1,42 @@
+set(POLICY_SRC_DIR ${PROJECT_SOURCE_DIR}/policy)
+set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/out)
+set(DOC_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/source)
+set(DOC_SOURCE_WORKDIR ${CMAKE_CURRENT_BINARY_DIR}/source)
+
+file(GLOB_RECURSE DOC_SOURCES FOLLOW_SYMLINKS "*")
+
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
+               ${CMAKE_CURRENT_BINARY_DIR}/conf.py
+               @ONLY)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate_reST_docs.py.in
+               ${CMAKE_CURRENT_BINARY_DIR}/generate_reST_docs.py
+               @ONLY)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/scripts/BroToReST.py.in
+               ${CMAKE_CURRENT_BINARY_DIR}/BroToReST.py
+               @ONLY)
+
+add_custom_target(doc
+                  COMMAND "${CMAKE_COMMAND}" -E copy_directory
+                          ${DOC_SOURCE_DIR}
+                          ${DOC_SOURCE_WORKDIR}
+                  COMMAND python generate_reST_docs.py
+                  COMMAND sphinx-build
+                          -b html
+                          -c ${CMAKE_CURRENT_BINARY_DIR}
+                          -d ${DOC_OUTPUT_DIR}/doctrees
+                          ${DOC_SOURCE_WORKDIR}
+                          ${DOC_OUTPUT_DIR}/html
+                  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                  COMMENT "[Sphinx] Generating Script Documentation"
+                  VERBATIM
+                  # SOURCES just adds stuff to IDE projects as a convienience
+                  SOURCES ${DOC_SOURCES})
+
+add_dependencies(doc bro doc-clean)
+
+add_custom_target(doc-clean
+                  COMMAND "${CMAKE_COMMAND}" -E remove_directory
+                          ${CMAKE_CURRENT_BINARY_DIR}/source
+                  COMMAND "${CMAKE_COMMAND}" -E remove_directory
+                          ${DOC_OUTPUT_DIR}
+                  VERBATIM)

doc/scripts/README

@@ -0,0 +1,44 @@
+This directory contains scripts and templates that can be used to automate
+the generation of Bro script documentation.  Two build targets are defined
+by CMake:
+
+``make doc``
+
+    This target depends on a Python interpreter (>=2.5) and
+    `Sphinx <http://sphinx.pocoo.org/>`_ being installed.  Sphinx can be
+    installed like::
+
+        > sudo easy_install sphinx
+
+    This target will also first build the bro binary if it is not already
+    since the generation of reStructuredText (reST) documentation from
+    Bro scripts is integrated within the parsing process.
+
+    After completion, HTML documentation can be located inside the CMake
+    ``build/`` directory as ``doc/scripts/out/html``.  The generated
+    reST documentation will be located in ``doc/scripts/source/policy``.
+
+``make doc-clean``
+
+    This target removes Sphinx inputs and outputs from the CMake ``build/`` dir.
+
+To schedule a script to be documented, edit ``scripts/generate_reST_docs.py.in``
+and try adding the name of the script along with an optional script group to
+the ``docs`` dictionary.  That python script also shows other, more specialized
+methods for generating documentation for some types of corner-cases.
+
+When adding a new logical grouping for generated scripts, create a new
+reST document in ``source/policy/<group_name>.rst`` and add some default
+documentation.  References to (and summaries of) documents associated with
+the group get appended to this file during the ``make doc`` process.
+
+The Sphinx source tree template in ``source/`` can be modified to add more
+common/general documentation, style sheets, JavaScript, etc.  The Sphinx
+config file is produced from ``conf.py.in``, so that can be edited to change
+various Sphinx options, like setting the default HTML rendering theme.
+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.
+
+See ``example.bro`` for an example of how to document a Bro script such that
+``make doc`` will be able to produce reST/HTML documentation for it.

doc/scripts/scripts/generate_reST_docs.py.in

@@ -44,7 +44,7 @@ GenDocs(stdin_docs, True)
 
 # The example documentation script doesn't live on the BROPATH, so
 # explicitly generate the docs for it like this:
-BroToReST("example.bro", False, ["@PROJECT_SOURCE_DIR@/doc"], group="internal").GenDoc()
+BroToReST("example.bro", False, ["@PROJECT_SOURCE_DIR@/doc/scripts"], group="internal").GenDoc()
 
 # Generate documentation for stuff that's always loaded into bro by default:
 cmd = "echo '' | %s %s" % (BRO, BRO_ARGS)

testing/btest/doc/autogen-reST-example

@@ -1,2 +1,2 @@
-@TEST-EXEC: bro --doc-scripts $DIST/doc/example.bro
+@TEST-EXEC: bro --doc-scripts $DIST/doc/scripts/example.bro
 @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/doc/example-diff-canonifier.py btest-diff example.rst