mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
Remove unused Sphinx extensions
This commit is contained in:
Jon Siwek
parent
7e9d48f532
commit
2a3a66fce2
3 changed files with 1 additions and 348 deletions
|
|
@ -26,7 +26,7 @@ sys.path.insert(0, os.path.abspath('ext'))
|
|||
|
||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions += ['bro', 'rst_directive', 'sphinx.ext.todo', 'adapt-toc']
|
||||
extensions += ['bro', 'rst_directive', 'sphinx.ext.todo']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates', '_static']
|
||||
|
|
|
|||
|
|
@ -1,29 +0,0 @@
|
|||
|
||||
import sys
|
||||
import re
|
||||
|
||||
# Removes the first TOC level, which is just the page title.
|
||||
def process_html_toc(app, pagename, templatename, context, doctree):
|
||||
|
||||
if not "toc" in context:
|
||||
return
|
||||
|
||||
toc = context["toc"]
|
||||
|
||||
lines = toc.strip().split("\n")
|
||||
lines = lines[2:-2]
|
||||
|
||||
toc = "\n".join(lines)
|
||||
toc = "<ul>" + toc
|
||||
|
||||
context["toc"] = toc
|
||||
|
||||
# print >>sys.stderr, pagename
|
||||
# print >>sys.stderr, context["toc"]
|
||||
# print >>sys.stderr, "-----"
|
||||
# print >>sys.stderr, toc
|
||||
# print >>sys.stderr, "===="
|
||||
|
||||
def setup(app):
|
||||
app.connect('html-page-context', process_html_toc)
|
||||
|
||||
|
|
@ -1,318 +0,0 @@
|
|||
"""
|
||||
Broxygen domain for Sphinx.
|
||||
|
||||
Adds directives that allow Sphinx to invoke Bro in order to generate script
|
||||
reference documentation on the fly. The directives are:
|
||||
|
||||
broxygen:package
|
||||
- Shows links to all scripts contained within matching package(s).
|
||||
broxygen:package_index
|
||||
- An index with links to matching package document(s).
|
||||
broxygen:script
|
||||
- Reference for matching script(s) (i.e. everything declared by the script).
|
||||
broxygen:script_summary
|
||||
- Shows link to matching script(s) with it's summary-section comments.
|
||||
broxygen:script_index
|
||||
- An index with links to all matching scrips.
|
||||
broxygen:proto_analyzer
|
||||
- All protocol analyzers and their components (events/bifs, etc.)
|
||||
broxygen:file_analyzer
|
||||
- All file analyzers and their components (events/bifs, etc.)
|
||||
"""
|
||||
|
||||
|
||||
from sphinx.domains import Domain, ObjType
|
||||
from sphinx.locale import l_
|
||||
from sphinx.util import logging
|
||||
from docutils.parsers.rst.directives.misc import Include
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
App = None
|
||||
|
||||
|
||||
def info(msg):
|
||||
"""Use Sphinx builder to output a console message."""
|
||||
global App
|
||||
from sphinx.util.console import blue
|
||||
logger.info(blue(msg))
|
||||
|
||||
|
||||
def pattern_to_filename_component(pattern):
|
||||
"""Replace certain characters in Broxygen config file target pattern.
|
||||
|
||||
Such that it can be used as part of a (sane) filename.
|
||||
|
||||
"""
|
||||
return pattern.replace("/", ".").replace("*", "star")
|
||||
|
||||
|
||||
def ensure_dir(path):
|
||||
"""Should act like ``mkdir -p``."""
|
||||
import os
|
||||
import errno
|
||||
|
||||
try:
|
||||
os.makedirs(path)
|
||||
except OSError as e:
|
||||
if e.errno != errno.EEXIST:
|
||||
raise
|
||||
|
||||
|
||||
def generate_config(env, type, pattern):
|
||||
"""Create a Broxygen config file for a particular target.
|
||||
|
||||
It can be used by Bro to generate reST docs for that target.
|
||||
|
||||
"""
|
||||
import os
|
||||
import tempfile
|
||||
from sphinx.errors import SphinxError
|
||||
|
||||
work_dir = env.config.broxygen_cache
|
||||
|
||||
if not work_dir:
|
||||
raise SphinxError("broxygen_cache not set in sphinx config file")
|
||||
|
||||
ensure_dir(work_dir)
|
||||
prefix = "{0}-{1}-".format(type, pattern_to_filename_component(pattern))
|
||||
(fd, cfg) = tempfile.mkstemp(suffix=".cfg", prefix=prefix, dir=work_dir)
|
||||
generated_file = "{0}.rst".format(cfg)
|
||||
config = "{0}\t{1}\t{2}".format(type, pattern, generated_file)
|
||||
f = os.fdopen(fd, "w")
|
||||
f.write(config)
|
||||
f.close()
|
||||
return (cfg, generated_file)
|
||||
|
||||
|
||||
def generate_target(env, type, pattern):
|
||||
"""Create a Broxygen target and build it.
|
||||
|
||||
For a target which hasn't been referenced by any other script, this function
|
||||
creates an associated config file then uses Bro w/ it to build the target
|
||||
and stores the target information in the build environment.
|
||||
|
||||
If a script references a target that's already found in the build
|
||||
environment the results of the previous built are re-used.
|
||||
|
||||
"""
|
||||
app_data = env.domaindata["broxygen"]
|
||||
|
||||
if (type, pattern) in app_data["targets"]:
|
||||
info("Broxygen has cached doc for target '{0} {1}'".format(
|
||||
type, pattern))
|
||||
return app_data["targets"]
|
||||
|
||||
(cfg, gend_file) = generate_config(env, type, pattern)
|
||||
target = BroxygenTarget(type, pattern, cfg, gend_file)
|
||||
app_data["targets"][(type, pattern)] = target
|
||||
build_target(env, target)
|
||||
info("Broxygen built target '{0} {1}'".format(type, pattern))
|
||||
return target
|
||||
|
||||
|
||||
def build_target(env, target):
|
||||
"""Invoke a Bro process to build a Broxygen target."""
|
||||
import os
|
||||
import subprocess
|
||||
|
||||
path_to_bro = env.config.bro_binary
|
||||
|
||||
if not path_to_bro:
|
||||
raise SphinxError("'bro' not set in sphinx config file (path to bro)")
|
||||
|
||||
bro_cmd = "{0} -X {1} broxygen".format(path_to_bro, target.config_file)
|
||||
cwd = os.getcwd()
|
||||
os.chdir(os.path.dirname(target.config_file))
|
||||
|
||||
try:
|
||||
subprocess.check_output(bro_cmd, stderr=subprocess.STDOUT, shell=True)
|
||||
except subprocess.CalledProcessError as e:
|
||||
from sphinx.errors import SphinxError
|
||||
raise SphinxError(
|
||||
"Command '{0}' returned non-zero exit status {1}: {2}".format(
|
||||
e.cmd, e.returncode, e.output))
|
||||
finally:
|
||||
os.chdir(cwd)
|
||||
|
||||
|
||||
class BroxygenTarget(object):
|
||||
|
||||
"""Some portion of reST documentation that Bro knows how to generate.
|
||||
|
||||
A target is identified by its type and pattern. E.g. type "script" and
|
||||
pattern "broxygen/example.bro".
|
||||
|
||||
"""
|
||||
|
||||
def __init__(self, type, pattern, config_file, generated_file):
|
||||
self.type = type
|
||||
self.pattern = pattern
|
||||
self.config_file = config_file
|
||||
self.generated_file = generated_file
|
||||
self.used_in_docs = set()
|
||||
|
||||
|
||||
class BroxygenDirective(Include):
|
||||
|
||||
"""Base class for Broxygen directives.
|
||||
|
||||
It can use Bro to generate reST documentation on the fly and embed it in
|
||||
the document at the location of the directive just like the ``.. include::``
|
||||
directive. The only argument is a pattern to identify to Bro which
|
||||
pieces of documentation it needs to create.
|
||||
"""
|
||||
|
||||
required_arguments = 1
|
||||
has_content = False
|
||||
|
||||
target_type = None
|
||||
|
||||
def run(self):
|
||||
env = self.state.document.settings.env
|
||||
info("Broxygen running .. {0}:: {1} in {2}".format(
|
||||
self.name, self.arguments[0], env.docname))
|
||||
target = generate_target(env, self.target_type, self.arguments[0])
|
||||
target.used_in_docs.add(env.docname)
|
||||
self.arguments = [target.generated_file]
|
||||
return super(BroxygenDirective, self).run()
|
||||
|
||||
|
||||
class PackageDirective(BroxygenDirective):
|
||||
|
||||
target_type = "package"
|
||||
|
||||
|
||||
class PackageIndexDirective(BroxygenDirective):
|
||||
|
||||
target_type = "package_index"
|
||||
|
||||
|
||||
class ScriptDirective(BroxygenDirective):
|
||||
|
||||
target_type = "script"
|
||||
|
||||
|
||||
class ScriptSummaryDirective(BroxygenDirective):
|
||||
|
||||
target_type = "script_summary"
|
||||
|
||||
|
||||
class ScriptIndexDirective(BroxygenDirective):
|
||||
|
||||
target_type = "script_index"
|
||||
|
||||
|
||||
class ProtoAnalyzerDirective(BroxygenDirective):
|
||||
|
||||
target_type = "proto_analyzer"
|
||||
|
||||
|
||||
class FileAnalyzerDirective(BroxygenDirective):
|
||||
|
||||
target_type = "file_analyzer"
|
||||
|
||||
|
||||
class IdentifierDirective(BroxygenDirective):
|
||||
|
||||
target_type = "identifier"
|
||||
|
||||
|
||||
class BroxygenDomain(Domain):
|
||||
|
||||
name = "broxygen"
|
||||
label = "Broxygen"
|
||||
|
||||
object_types = {
|
||||
"package": ObjType(l_("package")),
|
||||
"package_index": ObjType(l_("package_index")),
|
||||
"script": ObjType(l_("script")),
|
||||
"script_summary": ObjType(l_("script_summary")),
|
||||
"script_index": ObjType(l_("script_index")),
|
||||
"proto_analyzer": ObjType(l_("proto_analyzer")),
|
||||
"file_analyzer": ObjType(l_("file_analyzer")),
|
||||
"identifier": ObjType(l_("identifier")),
|
||||
}
|
||||
|
||||
directives = {
|
||||
"package": PackageDirective,
|
||||
"package_index": PackageIndexDirective,
|
||||
"script": ScriptDirective,
|
||||
"script_summary": ScriptSummaryDirective,
|
||||
"script_index": ScriptIndexDirective,
|
||||
"proto_analyzer": ProtoAnalyzerDirective,
|
||||
"file_analyzer": FileAnalyzerDirective,
|
||||
"identifier": IdentifierDirective,
|
||||
}
|
||||
|
||||
roles = {}
|
||||
|
||||
initial_data = {
|
||||
"targets": {}
|
||||
}
|
||||
|
||||
def clear_doc(self, docname):
|
||||
"""Update Broxygen targets referenced in docname.
|
||||
|
||||
If it's the last place the target was referenced, remove it from
|
||||
the build environment and delete any generated config/reST files
|
||||
associated with it from the cache.
|
||||
|
||||
"""
|
||||
import os
|
||||
|
||||
stale_targets = []
|
||||
|
||||
for (type, pattern), target in self.data["targets"].items():
|
||||
if docname in target.used_in_docs:
|
||||
target.used_in_docs.remove(docname)
|
||||
|
||||
if not target.used_in_docs:
|
||||
stale_targets.append(target)
|
||||
|
||||
for target in stale_targets:
|
||||
del self.data["targets"][(target.type, target.pattern)]
|
||||
os.remove(target.config_file)
|
||||
os.remove(target.generated_file)
|
||||
|
||||
def get_objects(self):
|
||||
"""No Broxygen-generated content is itself linkable/searchable."""
|
||||
return []
|
||||
|
||||
|
||||
def env_get_outdated_hook(app, env, added, changed, removed):
|
||||
"""Check whether to re-read any documents referencing Broxygen targets.
|
||||
|
||||
To do that we have to ask Bro to rebuild each target and compare the
|
||||
before and after modification times of the generated reST output file.
|
||||
If Bro changed it, then the document containing the Broxygen directive
|
||||
needs to be re-read.
|
||||
|
||||
"""
|
||||
import os
|
||||
|
||||
reread = set()
|
||||
|
||||
for target in app.env.domaindata["broxygen"]["targets"].values():
|
||||
before_mtime = os.stat(target.generated_file)
|
||||
build_target(env, target)
|
||||
after_mtime = os.stat(target.generated_file)
|
||||
|
||||
if after_mtime > before_mtime:
|
||||
info("Broxygen target '{0} {1}' outdated".format(
|
||||
target.type, target.pattern))
|
||||
|
||||
for docname in target.used_in_docs:
|
||||
if docname not in removed:
|
||||
info(" in document: {0}".format(docname))
|
||||
reread.add(docname)
|
||||
|
||||
return list(reread)
|
||||
|
||||
|
||||
def setup(app):
|
||||
global App
|
||||
App = app
|
||||
app.add_domain(BroxygenDomain)
|
||||
app.add_config_value("bro_binary", None, "env")
|
||||
app.add_config_value("broxygen_cache", None, "env")
|
||||
app.connect("env-get-outdated", env_get_outdated_hook)
|
||||
Loading…
Add table
Add a link
Reference in a new issue