Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-12 11:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Changes to make generated script docs understand new policy/ hierarchy.

Browse source 
Added an arg to the search_for_files() util function that can return
the subpath of BROPATH's policy/ dir in which the loaded file is found.
This subpath is then used in both the the reST file's document title
(so that script's named e.g. "base.bro" actually have some context) and
in figuring out how to interlink with other generated docs of other
scripts that are found in @load directives.

I still need to overhaul things so the loading of "packages" is
documented in a meaningful way and that the CMake targets are able
to generate indexes for packages.
This commit is contained in:
Jon Siwek 2011-06-30 11:37:15 -05:00
parent f307a3f408
commit fe5f4b8e53
12 changed files with 262 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

98
src/BroDoc.cc
View file

@ -3,9 +3,11 @@
#include <string>
#include <list>
#include <algorithm>
#include <libgen.h>
#include "BroDoc.h"
#include "BroDocObj.h"
#include "util.h"
BroDoc::BroDoc(const std::string& rel, const std::string& abs)
{
@ -15,25 +17,19 @@ BroDoc::BroDoc(const std::string& rel, const std::string& abs)
else
source_filename = abs.substr(f_pos + 1);
if ( rel == abs )
if ( rel[0] == '/' || rel[0] == '.' )
{
// The Bro script must have been loaded from an explicit path,
// so just use the basename as the document title
// The Bro script must not be on a subpath of the policy/ dir of
// BROPATH, so just use the basename as the document title
doc_title = source_filename;
}
else
{
// Must have relied on BROPATH to load the script, keep the relative
// directory as part of the source file name
size_t ext_pos = rel.find_last_of('.');
std::string rel_ext = rel.substr(ext_pos + 1);
ext_pos = abs.find_last_of('.');
std::string abs_ext = abs.substr(ext_pos + 1);
if ( rel_ext == abs_ext || std::string::npos == ext_pos )
doc_title = rel;
// keep the relative directory as part of the document title
if ( rel.size() == 0 || rel[rel.size() - 1] == '/' )
doc_title = rel + source_filename;
else
doc_title = rel + "." + abs_ext;
doc_title = rel + "/" + source_filename;
}
reST_filename = doc_title;
@ -46,24 +42,6 @@ BroDoc::BroDoc(const std::string& rel, const std::string& abs)
reST_filename = doc_title.substr(0, ext_pos);
reST_filename += ".rst";
/*
// if the bro source file is being loaded from a relative path,
// re-create that directory tree to store the output
size_t f_pos = reST_filename.find_last_of('/');
if ( std::string::npos != f_pos )
{
std::string outdir = reST_filename.substr(0, f_pos);
std::string subdir;
while ( ! outdir.empty() )
{
size_t pos = outdir.find_first_of('/');
if ( pos != std::string::npos ) pos++;
subdir += outdir.substr(0, pos);
outdir.erase(0, pos);
ensure_dir(subdir.c_str());
}
}
*/
// Instead of re-creating the directory hierarchy based on related
// loads, just replace the directory separatories such that the reST
// output will all be placed in a flat directory (the working dir).
@ -76,7 +54,7 @@ BroDoc::BroDoc(const std::string& rel, const std::string& abs)
#ifdef DEBUG
fprintf(stdout, "Documenting absolute source: %s\n", abs.c_str());
fprintf(stdout, "\trelative load: %s\n", rel.c_str());
fprintf(stdout, "\trelative dir: %s\n", rel.c_str());
fprintf(stdout, "\tdoc title: %s\n", doc_title.c_str());
fprintf(stdout, "\tbro file: %s\n", source_filename.c_str());
fprintf(stdout, "\trst file: %s\n", reST_filename.c_str());
@ -93,12 +71,60 @@ BroDoc::~BroDoc()
void BroDoc::AddImport(const std::string& s)
{
size_t ext_pos = s.find_last_of('.');
std::string lname(s);
// first strip any .bro extension
size_t ext_pos = lname.find(".bro");
if ( ext_pos != std::string::npos )
lname = lname.substr(0, ext_pos);
if ( ext_pos == std::string::npos )
imports.push_back(s);
const char* full_filename = "<error>";
const char* subpath = "<error>";
FILE* f = search_for_file(lname.c_str(), "bro", &full_filename, true,
&subpath);
if ( f )
{
fclose(f);
char* tmp = copy_string(full_filename);
char* filename = basename(tmp);
extern char* PACKAGE_LOADER;
if ( streq(filename, PACKAGE_LOADER) )
{
// link to the package's index
// TODO: check that this works
string pkg(subpath);
pkg += "/index";
imports.push_back(pkg);
}
else
{
if ( subpath[0] == '/' || subpath[0] == '.' )
{
// it's not a subpath of policy/, so just add the name of it
// as it's given in the @load directive
imports.push_back(lname);
}
else
{
// combine the base file name of script in the @load directive
// with the subpath of BROPATH's policy/ directory
string fname(subpath);
char* othertmp = copy_string(lname.c_str());
fname.append("/").append(basename(othertmp));
imports.push_back(fname);
delete [] othertmp;
}
}
delete [] tmp;
delete [] full_filename;
delete [] subpath;
}
else
imports.push_back(s.substr(0, ext_pos));
fprintf(stderr, "Failed to document '@load %s' in file: %s\n",
s.c_str(), reST_filename.c_str());
}
void BroDoc::SetPacketFilter(const std::string& s)