From 4634d92394ee1e887da151d8dcb35f7c28f56eb8 Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Wed, 20 Apr 2011 21:11:32 -0500 Subject: [PATCH] Move stuff related to policy script documentation from doc/ to doc/scripts/ --- doc/CMakeLists.txt | 43 +----------------- doc/README | 45 +------------------ doc/scripts/CMakeLists.txt | 42 +++++++++++++++++ doc/scripts/README | 44 ++++++++++++++++++ doc/{ => scripts}/conf.py.in | 0 doc/{ => scripts}/example.bro | 0 doc/scripts/{ => scripts}/BroToReST.py.in | 0 .../{ => scripts}/generate_reST_docs.py.in | 2 +- doc/{ => scripts}/source/_static/showhide.js | 0 .../source/_templates/layout.html | 0 doc/{ => scripts}/source/builtins.rst | 0 doc/{ => scripts}/source/common.rst | 0 doc/{ => scripts}/source/ext/bro.py | 0 doc/{ => scripts}/source/index.rst | 0 doc/{ => scripts}/source/policy/bifs.rst | 0 doc/{ => scripts}/source/policy/default.rst | 0 doc/{ => scripts}/source/policy/index.rst | 0 doc/{ => scripts}/source/policy/internal.rst | 0 doc/{ => scripts}/source/policy/user.rst | 0 testing/btest/doc/autogen-reST-example | 2 +- 20 files changed, 90 insertions(+), 88 deletions(-) create mode 100644 doc/scripts/CMakeLists.txt create mode 100644 doc/scripts/README rename doc/{ => scripts}/conf.py.in (100%) rename doc/{ => scripts}/example.bro (100%) rename doc/scripts/{ => scripts}/BroToReST.py.in (100%) rename doc/scripts/{ => scripts}/generate_reST_docs.py.in (95%) rename doc/{ => scripts}/source/_static/showhide.js (100%) rename doc/{ => scripts}/source/_templates/layout.html (100%) rename doc/{ => scripts}/source/builtins.rst (100%) rename doc/{ => scripts}/source/common.rst (100%) rename doc/{ => scripts}/source/ext/bro.py (100%) rename doc/{ => scripts}/source/index.rst (100%) rename doc/{ => scripts}/source/policy/bifs.rst (100%) rename doc/{ => scripts}/source/policy/default.rst (100%) rename doc/{ => scripts}/source/policy/index.rst (100%) rename doc/{ => scripts}/source/policy/internal.rst (100%) rename doc/{ => scripts}/source/policy/user.rst (100%) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 00e0974919..e2c3f25f4e 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,42 +1 @@ -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) +add_subdirectory(scripts) diff --git a/doc/README b/doc/README index 150260ed09..1333ed77b7 100644 --- a/doc/README +++ b/doc/README @@ -1,44 +1 @@ -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 `_ 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/.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. +TODO diff --git a/doc/scripts/CMakeLists.txt b/doc/scripts/CMakeLists.txt new file mode 100644 index 0000000000..00e0974919 --- /dev/null +++ b/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) diff --git a/doc/scripts/README b/doc/scripts/README new file mode 100644 index 0000000000..b7114ec262 --- /dev/null +++ b/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 `_ 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/.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. diff --git a/doc/conf.py.in b/doc/scripts/conf.py.in similarity index 100% rename from doc/conf.py.in rename to doc/scripts/conf.py.in diff --git a/doc/example.bro b/doc/scripts/example.bro similarity index 100% rename from doc/example.bro rename to doc/scripts/example.bro diff --git a/doc/scripts/BroToReST.py.in b/doc/scripts/scripts/BroToReST.py.in similarity index 100% rename from doc/scripts/BroToReST.py.in rename to doc/scripts/scripts/BroToReST.py.in diff --git a/doc/scripts/generate_reST_docs.py.in b/doc/scripts/scripts/generate_reST_docs.py.in similarity index 95% rename from doc/scripts/generate_reST_docs.py.in rename to doc/scripts/scripts/generate_reST_docs.py.in index 3278c42367..c54146314f 100755 --- a/doc/scripts/generate_reST_docs.py.in +++ b/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) diff --git a/doc/source/_static/showhide.js b/doc/scripts/source/_static/showhide.js similarity index 100% rename from doc/source/_static/showhide.js rename to doc/scripts/source/_static/showhide.js diff --git a/doc/source/_templates/layout.html b/doc/scripts/source/_templates/layout.html similarity index 100% rename from doc/source/_templates/layout.html rename to doc/scripts/source/_templates/layout.html diff --git a/doc/source/builtins.rst b/doc/scripts/source/builtins.rst similarity index 100% rename from doc/source/builtins.rst rename to doc/scripts/source/builtins.rst diff --git a/doc/source/common.rst b/doc/scripts/source/common.rst similarity index 100% rename from doc/source/common.rst rename to doc/scripts/source/common.rst diff --git a/doc/source/ext/bro.py b/doc/scripts/source/ext/bro.py similarity index 100% rename from doc/source/ext/bro.py rename to doc/scripts/source/ext/bro.py diff --git a/doc/source/index.rst b/doc/scripts/source/index.rst similarity index 100% rename from doc/source/index.rst rename to doc/scripts/source/index.rst diff --git a/doc/source/policy/bifs.rst b/doc/scripts/source/policy/bifs.rst similarity index 100% rename from doc/source/policy/bifs.rst rename to doc/scripts/source/policy/bifs.rst diff --git a/doc/source/policy/default.rst b/doc/scripts/source/policy/default.rst similarity index 100% rename from doc/source/policy/default.rst rename to doc/scripts/source/policy/default.rst diff --git a/doc/source/policy/index.rst b/doc/scripts/source/policy/index.rst similarity index 100% rename from doc/source/policy/index.rst rename to doc/scripts/source/policy/index.rst diff --git a/doc/source/policy/internal.rst b/doc/scripts/source/policy/internal.rst similarity index 100% rename from doc/source/policy/internal.rst rename to doc/scripts/source/policy/internal.rst diff --git a/doc/source/policy/user.rst b/doc/scripts/source/policy/user.rst similarity index 100% rename from doc/source/policy/user.rst rename to doc/scripts/source/policy/user.rst diff --git a/testing/btest/doc/autogen-reST-example b/testing/btest/doc/autogen-reST-example index c47a604373..7f55384ce6 100644 --- a/testing/btest/doc/autogen-reST-example +++ b/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