Changed make doc target to re-use Sphinx cache.

To do this, the document root and autogenerated bro script docs
are rsync'd in to Sphinx's working directory instead of a plain
recursive copy.  There are still some index files that are auto
generated on each build and will trigger Sphinx to re-build them
since it thinks they changed, but overall the build is much faster
this way.

One limitation of this is that old files in the Sphinx work dir
don't automatically get cleaned up (e.g. if you remove some static
documentation from the /doc it will still be in
build/doc/sphinx-sources).  So a `make docclean` or at least
`make broxygenclean` is needed at least in that case.  (For now,
rsync --delete isn't the right answer since the destination of
the autogenerated stuff overlaps with the document root, the separate
rsyncs end up clobbering each other.)

doc/CMakeLists.txt

@@ -21,13 +21,13 @@ add_subdirectory(scripts)
 add_custom_target(broxygen
                   # copy the template documentation to the build directory
                   # to give as input for sphinx
-                  COMMAND "${CMAKE_COMMAND}" -E copy_directory
+                  COMMAND rsync -r --copy-links --times
-                          ${DOC_SOURCE_DIR}
+                          ${DOC_SOURCE_DIR}/
                           ${DOC_SOURCE_WORKDIR}
                   # copy generated policy script documentation into the
                   # working copy of the template documentation
-                  COMMAND "${CMAKE_COMMAND}" -E copy_directory
+                  COMMAND rsync -r --copy-links --times
-                          ${RST_OUTPUT_DIR}
+                          ${RST_OUTPUT_DIR}/
                           ${DOC_SOURCE_WORKDIR}/scripts
                   # append to the master index of all policy scripts
                   COMMAND cat ${MASTER_POLICY_INDEX} >>
@@ -58,7 +58,7 @@ add_custom_target(broxygen
                   # SOURCES just adds stuff to IDE projects as a convenience
                   SOURCES ${DOC_SOURCES})
 
-# The "sphinxclean" target removes just the Sphinx input/output directories
+# The "broxygenclean" target removes just the Sphinx input/output directories
 # from the build directory.
 add_custom_target(broxygenclean
                   COMMAND "${CMAKE_COMMAND}" -E remove_directory
@@ -67,7 +67,7 @@ add_custom_target(broxygenclean
                           ${DOC_OUTPUT_DIR}
                   VERBATIM)
 
-add_dependencies(broxygen broxygenclean restdoc)
+add_dependencies(broxygen restdoc)
 
 add_custom_target(doc)
 add_custom_target(docclean)

doc/bin/group_index_generator.py

@@ -8,9 +8,11 @@
 # 2nd argument is the directory containing ${group}_files lists of
 #   scripts that belong to the group and ${group}_doc_names lists of
 #   document names that can be supplied to a reST :doc: role
-# 3rd argument is a directory in which write a ${group}.rst file (will
+# 3rd argument is a directory in which write a ${group}.rst file that contains
-#   append to existing file) that contains reST style references to
+#   reST style references to script docs along with summary text contained
-#   script docs along with summary text contained in original script
+#   in original script.  If ${group} ends with "index", then the file
+#   is always clobbered by this script, but for other unique group names,
+#   this script will append to existing files.
 
 import sys
 import os
@@ -20,9 +22,28 @@ group_list = sys.argv[1]
 file_manifest_dir = sys.argv[2]
 output_dir = sys.argv[3]
 
+def make_group_file_index(dir_name, group_name):
+    group_file = os.path.join(dir_name, group_name + ".rst")
+
+    if not os.path.exists(group_file):
+        if not os.path.exists(os.path.dirname(group_file)):
+            os.makedirs(os.path.dirname(group_file))
+
+    if group_name.endswith("index"):
+        with open(group_file, 'w') as f_group_file:
+            f_group_file.write(":orphan:\n\n")
+            title = "Package Index: %s\n" % os.path.dirname(group_name)
+            f_group_file.write(title);
+            for n in range(len(title)):
+                f_group_file.write("=")
+            f_group_file.write("\n");
+
+    return group_file
+
 with open(group_list, 'r') as f_group_list:
     for group in f_group_list.read().splitlines():
         #print group
+        group_file = make_group_file_index(output_dir, group)
         file_manifest = os.path.join(file_manifest_dir, group + "_files")
         doc_manifest = os.path.join(file_manifest_dir, group + "_doc_names")
         src_files = []
@@ -44,17 +65,6 @@ with open(group_list, 'r') as f_group_list:
                     if sum_pos != -1:
                         summary_comments.append(line[(sum_pos+3):])
             #print summary_comments
-            group_file = os.path.join(output_dir, group + ".rst")
-            if not os.path.exists(group_file):
-                if not os.path.exists(os.path.dirname(group_file)):
-                    os.makedirs(os.path.dirname(group_file))
-                with open(group_file, 'w') as f_group_file:
-                    f_group_file.write(":orphan:\n\n")
-                    title = "Package Index: %s\n" % os.path.dirname(group)
-                    f_group_file.write(title);
-                    for n in range(len(title)):
-                        f_group_file.write("=")
-                    f_group_file.write("\n");
 
             with open(group_file, 'a') as f_group_file:
                 f_group_file.write("\n:doc:`/scripts/%s`\n" % doc_names[i])