Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-03 07:08:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Changed make doc target to re-use Sphinx cache.

Browse source 
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.)
This commit is contained in:
Jon Siwek 2012-10-24 17:04:44 -05:00
parent 5f5bc53b85
commit 54a0f3a5ae
2 changed files with 30 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

12
doc/CMakeLists.txt
View file

@ -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
${DOC_SOURCE_DIR}
COMMAND rsync -r --copy-links --times
${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
${RST_OUTPUT_DIR}
COMMAND rsync -r --copy-links --times
${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)

38
doc/bin/group_index_generator.py
View file

@ -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
# append to existing file) that contains reST style references to
# script docs along with summary text contained in original script
# 3rd argument is a directory in which write a ${group}.rst file that contains
# reST style references to script docs along with summary text contained
# 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])