sphinxext-ip/jandd/sphinxext/ip.py

271 lines
8.3 KiB
Python
Raw Normal View History

# -*- coding: utf-8 -*-
"""
jandd.sphinxext.ip
~~~~~~~~~~~~~~~~~~
The IP domain.
:copyright: Copyright (c) 2016 Jan Dittberner
:license: GPLv3+, see COPYING file for details.
"""
2016-05-02 21:33:10 +02:00
__version__ = '0.1.1'
import re
from ipcalc import Network
from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx import addnodes
from sphinx.domains import Domain, ObjType
from sphinx.environment import NoUri
from sphinx.locale import l_
from sphinx.roles import XRefRole
from sphinx.util.nodes import make_refnode
def ip_object_anchor(typ, path):
path = re.sub(r'[.:/]', '-', path)
return typ.lower() + '-' + path
class ip_node(nodes.Inline, nodes.TextElement): pass
class ip_range(nodes.General, nodes.Element): pass
class IPXRefRole(XRefRole):
"""
Cross referencing role for the IP domain.
"""
def __init__(self, method, index_type, **kwargs):
self.method = method
self.index_type = index_type
innernodeclass=None
if method in ('v4', 'v6'):
innernodeclass = ip_node
super(IPXRefRole, self).__init__(
innernodeclass=innernodeclass, **kwargs)
def process_link(self, env, refnode, has_explicit_title, title, target):
domaindata = env.domaindata['ip']
domaindata[self.method][target] = (target, refnode)
return title, target
def result_nodes(self, document, env, node, is_ref):
2016-04-24 15:04:07 +02:00
try:
node['typ'] = self.method
2016-04-24 15:04:07 +02:00
indexnode = addnodes.index()
targetid = 'index-%s' % env.new_serialno('index')
targetnode = nodes.target('', '', ids=[targetid])
doctitle = document.traverse(nodes.title)[0].astext()
idxtext = "%s; %s" % (node.astext(), doctitle)
idxtext2 = "%s; %s" % (self.index_type, node.astext())
indexnode['entries'] = [
('single', idxtext, targetid, '', None),
('single', idxtext2, targetid, '', None),
]
2016-04-24 15:04:07 +02:00
return [indexnode, targetnode, node], []
except KeyError as e:
return [node], [e.args[0]]
class IPRange(Directive):
has_content = True
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = False
option_spec = {}
def handle_rangespec(self, node):
titlenode = nodes.title()
node.append(titlenode)
titlenode.append(nodes.inline('', self.get_prefix_title()))
titlenode.append(nodes.literal('', self.rangespec))
ids = ip_object_anchor(self.typ, self.rangespec)
node['ids'].append(ids)
self.env.domaindata[self.domain][self.typ][ids] = (
self.env.docname,
self.options.get('synopsis', ''))
return ids
def run(self):
if ':' in self.name:
self.domain, self.objtype = self.name.split(':', 1)
else:
self.domain, self.objtype = '', self.name
self.env = self.state.document.settings.env
self.rangespec = self.arguments[0]
node = nodes.section()
name = self.handle_rangespec(node)
if self.env.docname in self.env.titles:
doctitle = self.env.titles[self.env.docname]
else:
doctitle = self.state.document.traverse(nodes.title)[0].astext()
idx_text = "%s; %s" % (self.rangespec, doctitle)
self.indexnode = addnodes.index(entries=[
('single', idx_text, name, ''),
('single', self.get_index_text(), name, '')
])
if self.content:
contentnode = nodes.paragraph('')
node.append(contentnode)
self.state.nested_parse(
self.content, self.content_offset, contentnode)
iprange = ip_range()
node.append(iprange)
iprange['rangespec'] = self.rangespec
return [self.indexnode, node]
class IPv4Range(IPRange):
typ = 'v4range'
def get_prefix_title(self):
return l_('IPv4 address range ')
def get_index_text(self):
return "%s; %s" % (l_('IPv4 range'), self.rangespec)
class IPv6Range(IPRange):
typ = 'v6range'
def get_prefix_title(self):
return l_('IPv6 address range ')
def get_index_text(self):
return "%s; %s" % (l_('IPv6 range'), self.rangespec)
class IPDomain(Domain):
"""
IP address and range domain.
"""
name = 'ip'
label = 'IP addresses and ranges.'
object_types = {
'v4': ObjType(l_('v4'), 'v4', 'obj'),
'v6': ObjType(l_('v6'), 'v6', 'obj'),
'v4range': ObjType(l_('v4range'), 'v4range', 'obj'),
'v6range': ObjType(l_('v6range'), 'v6range', 'obj'),
}
directives = {
'v4range': IPv4Range,
'v6range': IPv6Range,
}
roles = {
'v4': IPXRefRole('v4', l_('IPv4 address')),
'v6': IPXRefRole('v6', l_('IPv6 address')),
'v4range': IPXRefRole('v4range', l_('IPv4 range')),
'v6range': IPXRefRole('v6range', l_('IPv6 range')),
}
initial_data = {
'v4': {},
'v6': {},
'v4range': {},
'v6range': {},
'ips': [],
}
def clear_doc(self, docname):
pass
def resolve_xref(self, env, fromdocname, builder, typ, target, node,
contnode):
key = ip_object_anchor(typ, target)
try:
info = self.data[typ][key]
except KeyError:
text = contnode.rawsource
role = self.roles.get(typ)
if role is None:
return None
resnode = role.result_nodes(env.get_doctree(fromdocname),
env, node, True)[0][2]
if isinstance(resnode, addnodes.pending_xref):
text = node[0][0]
reporter = env.get_doctree(fromdocname).reporter
reporter.warning('Cannot resolve reference to %r' % text,
line=node.line)
return node.children
return resnode
else:
title = typ.upper() + ' ' + target
return make_refnode(builder, fromdocname, info[0], key,
contnode, title)
@property
def items(self):
return dict((key, self.data[key]) for key in self.object_types)
def get_objects(self):
for typ, items in self.items.items():
for path, info in items.items():
anchor = ip_object_anchor(typ, path)
yield (path, path, typ, info[0], anchor, 1)
def process_ips(app, doctree):
env = app.builder.env
domaindata = env.domaindata[IPDomain.name]
for node in doctree.traverse(ip_node):
ip = node.astext()
domaindata['ips'].append({
'docname': env.docname,
'source': node.parent.source or env.doc2path(env.docname),
'lineno': node.parent.line,
'ip': ip,
'typ': node.parent['typ'],
})
replacement = nodes.literal(ip, ip)
node.replace_self(replacement)
def sort_ip_info(item):
return item['ip']
def process_ip_nodes(app, doctree, fromdocname):
env = app.builder.env
domaindata = env.domaindata[IPDomain.name]
for node in doctree.traverse(ip_range):
content = []
net = Network(node['rangespec'])
for ip_info in sorted(domaindata['ips'], key=sort_ip_info):
if ip_info['ip'] in net:
para = nodes.paragraph()
para += nodes.literal('', ip_info['ip'])
ids = ip_object_anchor(ip_info['typ'], ip_info['ip'])
para['ids'].append(ids)
domaindata[ip_info['typ']][ids] = (fromdocname, '')
newnode = nodes.reference('', '', internal=True)
try:
newnode['refuri'] = app.builder.get_relative_uri(
fromdocname, ip_info['docname'])
except NoUri:
pass
title = env.titles[ip_info['docname']]
innernode = nodes.Text(title.astext())
newnode.append(innernode)
para += nodes.Text(" in ")
para += newnode
content.append(para)
node.replace_self(content)
def setup(app):
app.add_domain(IPDomain)
app.connect('doctree-read', process_ips)
app.connect('doctree-resolved', process_ip_nodes)
return {'version': __version__}