Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 22:58:20 +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

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])