From fdf01a1ba663230914615858c92c863c9899d205 Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Tue, 15 Nov 2011 11:52:52 -0600 Subject: [PATCH] Finished dissolving the sphinx source directory into doc/ and doc/scripts/ --- doc/CMakeLists.txt | 8 +-- doc/{source => }/_static/broxygen.css | 0 doc/{source => }/_static/showhide.js | 0 doc/{source => }/_templates/layout.html | 0 doc/conf.py.in | 6 +- doc/{source => }/ext/bro.py | 0 doc/index.rst | 77 ++++++++++++++----------- doc/scripts/CMakeLists.txt | 2 +- doc/scripts/bifs.rst | 5 ++ doc/{source => scripts}/builtins.rst | 0 doc/{source => scripts}/common.rst | 0 doc/scripts/index.rst | 8 +++ doc/scripts/internal.rst | 5 ++ doc/{source => scripts}/packages.rst | 6 +- doc/source/bifs.rst | 5 -- doc/source/index.rst | 23 -------- doc/source/internal.rst | 5 -- doc/source/scripts/index.rst | 6 -- 18 files changed, 71 insertions(+), 85 deletions(-) rename doc/{source => }/_static/broxygen.css (100%) rename doc/{source => }/_static/showhide.js (100%) rename doc/{source => }/_templates/layout.html (100%) rename doc/{source => }/ext/bro.py (100%) create mode 100644 doc/scripts/bifs.rst rename doc/{source => scripts}/builtins.rst (100%) rename doc/{source => scripts}/common.rst (100%) create mode 100644 doc/scripts/index.rst create mode 100644 doc/scripts/internal.rst rename doc/{source => scripts}/packages.rst (78%) delete mode 100644 doc/source/bifs.rst delete mode 100644 doc/source/index.rst delete mode 100644 doc/source/internal.rst delete mode 100644 doc/source/scripts/index.rst diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 6567faae76..7685230980 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,8 +1,8 @@ set(BIF_SRC_DIR ${PROJECT_SOURCE_DIR}/src) set(RST_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/rest_output) 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) +set(DOC_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}) +set(DOC_SOURCE_WORKDIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx-sources) set(MASTER_POLICY_INDEX ${CMAKE_CURRENT_BINARY_DIR}/scripts/policy_index) set(MASTER_PACKAGE_INDEX ${CMAKE_CURRENT_BINARY_DIR}/scripts/pkg_index) @@ -34,12 +34,12 @@ add_custom_target(broxygen ${DOC_SOURCE_WORKDIR}/scripts/index.rst # append to the master index of all policy packages COMMAND cat ${MASTER_PACKAGE_INDEX} >> - ${DOC_SOURCE_WORKDIR}/packages.rst + ${DOC_SOURCE_WORKDIR}/scripts/packages.rst # construct a reST file for each group COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bin/group_index_generator.py ${CMAKE_CURRENT_BINARY_DIR}/scripts/group_list ${CMAKE_CURRENT_BINARY_DIR}/scripts - ${DOC_SOURCE_WORKDIR} + ${DOC_SOURCE_WORKDIR}/scripts # tell sphinx to generate html COMMAND sphinx-build -b html diff --git a/doc/source/_static/broxygen.css b/doc/_static/broxygen.css similarity index 100% rename from doc/source/_static/broxygen.css rename to doc/_static/broxygen.css diff --git a/doc/source/_static/showhide.js b/doc/_static/showhide.js similarity index 100% rename from doc/source/_static/showhide.js rename to doc/_static/showhide.js diff --git a/doc/source/_templates/layout.html b/doc/_templates/layout.html similarity index 100% rename from doc/source/_templates/layout.html rename to doc/_templates/layout.html diff --git a/doc/conf.py.in b/doc/conf.py.in index cee16b9239..34e92cd1f1 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -15,7 +15,7 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('source/ext')) +sys.path.insert(0, os.path.abspath('sphinx-sources/ext')) # -- General configuration ----------------------------------------------------- @@ -27,7 +27,7 @@ sys.path.insert(0, os.path.abspath('source/ext')) extensions = ['bro'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['source/_templates', 'source/_static'] +templates_path = ['sphinx-sources/_templates', 'sphinx-sources/_static'] # The suffix of source filenames. source_suffix = '.rst' @@ -143,7 +143,7 @@ html_theme_options = { # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['source/_static'] +html_static_path = ['sphinx-sources/_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/source/ext/bro.py b/doc/ext/bro.py similarity index 100% rename from doc/source/ext/bro.py rename to doc/ext/bro.py diff --git a/doc/index.rst b/doc/index.rst index c7c85bd21f..56a9e06fe8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,50 +1,57 @@ - +.. Bro documentation master file Bro Documentation ================= -`Getting Started <{{git('bro:doc/quickstart.rst')}}>`_ - A quick introduction into using Bro 2.x. +.. toctree:: + :maxdepth: 1 -`Bro 1.5 to 2.0 Upgrade Guide <{{git('bro:doc/upgrade.rst')}}>`_ - Guidelines and notes about upgrading from Bro 1.5 to 2.x. Lots of - things have changed, so make sure to read this when upgrading. - -`BroControl <{{git('broctl:doc/broctl.rst')}}>`_ - An interactive console for managing Bro installations. - -`Script Reference <{{autodoc_bro_scripts}}/index.html>`_ - A complete reference of all policy scripts shipped with Bro. - -`FAQ <{{docroot}}/documentation/faq.html>`_ - A list with frequently asked questions. - -`How to Report a Problem <{{docroot}}/documentation/reporting-problems.html>`_ - Some advice for when you see Bro doing something you believe it - shouldn't. + quickstart + upgrade + FAQ + Reporting Problems Frameworks ---------- -Bro comes with a number of frameworks, some of which are described in -more detail here: +.. toctree:: + :maxdepth: 1 -`Notice <{{git('bro:doc/notice.rst')}}>`_ - The notice framework. - -`Logging <{{git('bro:doc/logging.rst')}}>`_ - Customizing and extensing Bro's logging. - -`Cluster <{{git('bro:doc/cluster.rst')}}>`_ - Setting up a Bro Cluster when a single box can't handle the traffic anymore. - -`Signatures <{{git('bro:doc/signatures.rst')}}>`_ - Bro has support for traditional NIDS signatures as well. + notice + logging + cluster + signatures How-Tos ------- -We also collect more specific How-Tos on specific topics: +.. toctree:: + :maxdepth: 1 -`Using GeoIP in Bro scripts <{{git('bro:doc/geoip.rst')}}>`_ - Installation and usage of the the GeoIP library. + geoip + +Script Reference +---------------- + +.. toctree:: + :maxdepth: 1 + + scripts/common + scripts/builtins + scripts/bifs + scripts/packages + scripts/index + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`search` + +Internal References +------------------- + +.. toctree:: + :maxdepth: 1 + + scripts/internal diff --git a/doc/scripts/CMakeLists.txt b/doc/scripts/CMakeLists.txt index 377e686e6e..7b47424c6c 100644 --- a/doc/scripts/CMakeLists.txt +++ b/doc/scripts/CMakeLists.txt @@ -73,7 +73,7 @@ macro(REST_TARGET srcDir broInput) elseif (${extension} STREQUAL ".bif.bro") set(group bifs) elseif (relDstDir) - set(pkgIndex scripts/${relDstDir}/index) + set(pkgIndex ${relDstDir}/index) set(group ${pkgIndex}) # add package index to master package list if not already in it list(FIND MASTER_PKG_LIST ${pkgIndex} _found) diff --git a/doc/scripts/bifs.rst b/doc/scripts/bifs.rst new file mode 100644 index 0000000000..eaae0e13b8 --- /dev/null +++ b/doc/scripts/bifs.rst @@ -0,0 +1,5 @@ +.. This is a stub doc to which broxygen appends during the build process + +Built-In Functions (BIFs) +========================= + diff --git a/doc/source/builtins.rst b/doc/scripts/builtins.rst similarity index 100% rename from doc/source/builtins.rst rename to doc/scripts/builtins.rst diff --git a/doc/source/common.rst b/doc/scripts/common.rst similarity index 100% rename from doc/source/common.rst rename to doc/scripts/common.rst diff --git a/doc/scripts/index.rst b/doc/scripts/index.rst new file mode 100644 index 0000000000..5de203afe7 --- /dev/null +++ b/doc/scripts/index.rst @@ -0,0 +1,8 @@ +.. This is a stub doc to which broxygen appends during the build process + +Index of All Bro Scripts +======================== + +.. toctree:: + :maxdepth: 1 + diff --git a/doc/scripts/internal.rst b/doc/scripts/internal.rst new file mode 100644 index 0000000000..a6c10f1cfb --- /dev/null +++ b/doc/scripts/internal.rst @@ -0,0 +1,5 @@ +.. This is a stub doc to which broxygen appends during the build process + +Internal Scripts +================ + diff --git a/doc/source/packages.rst b/doc/scripts/packages.rst similarity index 78% rename from doc/source/packages.rst rename to doc/scripts/packages.rst index 35f6633fd4..47e974b0c8 100644 --- a/doc/source/packages.rst +++ b/doc/scripts/packages.rst @@ -1,7 +1,7 @@ -.. This is a stub doc to which the build process can append. +.. This is a stub doc to which broxygen appends during the build process -Bro Script Packages -=================== +Index of All Bro Script Packages +================================ Bro has the following script packages (e.g. collections of related scripts in a common directory). If the package directory contains a ``__load__.bro`` diff --git a/doc/source/bifs.rst b/doc/source/bifs.rst deleted file mode 100644 index 6a42cafafc..0000000000 --- a/doc/source/bifs.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -Built-In Functions (BIFs) -========================= - diff --git a/doc/source/index.rst b/doc/source/index.rst deleted file mode 100644 index a144644208..0000000000 --- a/doc/source/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. Bro documentation master file - -Welcome to Bro's documentation! -=============================== - -Contents: - -.. toctree:: - :maxdepth: 1 - :glob: - - common - builtins - internal - bifs - packages - scripts/index - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` diff --git a/doc/source/internal.rst b/doc/source/internal.rst deleted file mode 100644 index 817c76e725..0000000000 --- a/doc/source/internal.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -Internal Scripts -================ - diff --git a/doc/source/scripts/index.rst b/doc/source/scripts/index.rst deleted file mode 100644 index fd11a3924e..0000000000 --- a/doc/source/scripts/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -Index of All Bro Script Documentation -===================================== - -.. toctree:: - :maxdepth: 1 -