Compare commits
18 commits
Author | SHA1 | Date | |
---|---|---|---|
Jan Dittberner | 04985650e7 | ||
Jan Dittberner | 9d94b308ae | ||
Jan Dittberner | 1afe18b429 | ||
Jan Dittberner | 7c675a6fdb | ||
Jan Dittberner | c721d1bf9c | ||
Jan Dittberner | 6d425acaac | ||
Jan Dittberner | 7acff11695 | ||
Jan Dittberner | d1a151f8bd | ||
Jan Dittberner | 1451a5a1c0 | ||
Jan Dittberner | e53838acfb | ||
Jan Dittberner | 49a3d89488 | ||
Jan Dittberner | 8bc07c611f | ||
Jan Dittberner | 8044e1a071 | ||
Jan Dittberner | 80fad8cd49 | ||
Jan Dittberner | 43f01a1235 | ||
Jan Dittberner | fdb126996a | ||
Jan Dittberner | 0af66c6964 | ||
Jan Dittberner | 3daf568fb6 |
15
.gitignore
vendored
15
.gitignore
vendored
|
@ -2,11 +2,14 @@
|
||||||
*.pyc
|
*.pyc
|
||||||
*.pyo
|
*.pyo
|
||||||
.*.swp
|
.*.swp
|
||||||
.ropeproject/
|
|
||||||
__pycache__/
|
|
||||||
dist/
|
|
||||||
.coverage
|
.coverage
|
||||||
htmlcov/
|
|
||||||
build/
|
|
||||||
_build/
|
|
||||||
.idea/
|
.idea/
|
||||||
|
.ropeproject/
|
||||||
|
/.*_cache/
|
||||||
|
/.python-version
|
||||||
|
/.tox/
|
||||||
|
__pycache__/
|
||||||
|
_build/
|
||||||
|
build/
|
||||||
|
dist/
|
||||||
|
htmlcov/
|
||||||
|
|
32
CHANGES.rst
32
CHANGES.rst
|
@ -1,6 +1,38 @@
|
||||||
Changes
|
Changes
|
||||||
=======
|
=======
|
||||||
|
|
||||||
|
0.6.1 - 2023-01-29
|
||||||
|
------------------
|
||||||
|
|
||||||
|
* reupload to include namespace package
|
||||||
|
|
||||||
|
0.6.0 - 2023-01-29
|
||||||
|
------------------
|
||||||
|
|
||||||
|
* add development documentation in development.rst
|
||||||
|
* use tox as test runner
|
||||||
|
* add type annotations
|
||||||
|
* fix Sphinx 6 deprecation warnings
|
||||||
|
|
||||||
|
0.5.1 - 2021-09-04
|
||||||
|
------------------
|
||||||
|
|
||||||
|
* fix anchors in links
|
||||||
|
|
||||||
|
0.5.0 - 2021-09-04
|
||||||
|
------------------
|
||||||
|
|
||||||
|
* fix Docutils error
|
||||||
|
* adapt to Sphinx 4
|
||||||
|
|
||||||
|
0.4.0 - 2021-01-02
|
||||||
|
------------------
|
||||||
|
|
||||||
|
* fix Docutils deprecation warning
|
||||||
|
* fix test deprecation warning from Sphinx
|
||||||
|
* use pytest for testing
|
||||||
|
* switch to PEP-517 build API and metadata
|
||||||
|
|
||||||
0.3.0 - 2019-07-13
|
0.3.0 - 2019-07-13
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
|
|
47
DEVELOPMENT.rst
Normal file
47
DEVELOPMENT.rst
Normal file
|
@ -0,0 +1,47 @@
|
||||||
|
Development
|
||||||
|
===========
|
||||||
|
|
||||||
|
The extension is developed in a git repository that can be cloned by running::
|
||||||
|
|
||||||
|
git clone https://git.dittberner.info/jan/sphinxext-ip.git
|
||||||
|
|
||||||
|
Running test
|
||||||
|
------------
|
||||||
|
|
||||||
|
To install all dependencies and run the tests use::
|
||||||
|
|
||||||
|
pipenv install --dev
|
||||||
|
pipenv run tox
|
||||||
|
|
||||||
|
Release a new version
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Start by deciding the new release number and perform the following steps:
|
||||||
|
|
||||||
|
* update CHANGES.rst
|
||||||
|
* change ``version`` in setup.cfg
|
||||||
|
* change ``__version__`` in jandd/sphinxext/ip/__init__.rst
|
||||||
|
* change ``version`` in tests/root/conf.py
|
||||||
|
* commit and push your changes ::
|
||||||
|
|
||||||
|
git commit -m "Release <version>"
|
||||||
|
git push
|
||||||
|
|
||||||
|
* create an annotated and signed tag with the new version number (``git
|
||||||
|
shortlog <previous_tag>..HEAD`` could help to create a good release tag
|
||||||
|
message) ::
|
||||||
|
|
||||||
|
git tag -s -a <version>
|
||||||
|
|
||||||
|
* build the release artifacts ::
|
||||||
|
|
||||||
|
rm -rf dist jandd.sphinxext.ip.egg-info
|
||||||
|
pipenv run python3 setup.py egg_info -b <version< bdist_wheel sdist
|
||||||
|
|
||||||
|
* upload to PyPI using twine ::
|
||||||
|
|
||||||
|
pipenv run twine upload -s dist/*
|
||||||
|
|
||||||
|
* push the tag to git ::
|
||||||
|
|
||||||
|
git push --tags
|
|
@ -1,2 +1,2 @@
|
||||||
include README.rst
|
include README.rst CHANGES.rst
|
||||||
recursive-include tests/root *.rst Makefile conf.py
|
recursive-include tests/root *.rst Makefile conf.py
|
||||||
|
|
13
Pipfile
13
Pipfile
|
@ -4,14 +4,13 @@ url = "https://pypi.org/simple"
|
||||||
verify_ssl = true
|
verify_ssl = true
|
||||||
|
|
||||||
[dev-packages]
|
[dev-packages]
|
||||||
sphinx = ">=2"
|
|
||||||
path-py = ">=8.2.1"
|
|
||||||
ipcalc = ">=1.99"
|
|
||||||
coverage = "*"
|
coverage = "*"
|
||||||
twine = "*"
|
twine = "*"
|
||||||
|
pytest = "*"
|
||||||
|
tox = "*"
|
||||||
|
black = "*"
|
||||||
|
|
||||||
[packages]
|
[packages]
|
||||||
jandd-sphinxext-ip = {editable = true,path = "."}
|
jandd-sphinxext-ip = { path = ".", editable = true }
|
||||||
|
Sphinx = ">=5"
|
||||||
[requires]
|
docutils = "*"
|
||||||
python_version = "3.7"
|
|
||||||
|
|
1044
Pipfile.lock
generated
1044
Pipfile.lock
generated
File diff suppressed because it is too large
Load diff
|
@ -8,14 +8,6 @@ directives to collect information regarding IP addresses in IP ranges.
|
||||||
|
|
||||||
.. _Sphinx: http://www.sphinx-doc.org/
|
.. _Sphinx: http://www.sphinx-doc.org/
|
||||||
|
|
||||||
Development
|
|
||||||
===========
|
|
||||||
|
|
||||||
The extension is developed in a git repository that can be cloned by running::
|
|
||||||
|
|
||||||
git clone https://git.dittberner.info/jan/sphinxext-ip.git
|
|
||||||
|
|
||||||
|
|
||||||
Contributors
|
Contributors
|
||||||
============
|
============
|
||||||
|
|
||||||
|
|
|
@ -1 +0,0 @@
|
||||||
__import__('pkg_resources').declare_namespace(__name__)
|
|
|
@ -1 +0,0 @@
|
||||||
__import__('pkg_resources').declare_namespace(__name__)
|
|
|
@ -1,363 +0,0 @@
|
||||||
# -*- coding: utf-8 -*-
|
|
||||||
"""
|
|
||||||
jandd.sphinxext.ip
|
|
||||||
~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The IP domain.
|
|
||||||
|
|
||||||
:copyright: Copyright (c) 2016 Jan Dittberner
|
|
||||||
:license: GPLv3+, see COPYING file for details.
|
|
||||||
"""
|
|
||||||
|
|
||||||
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.errors import NoUri
|
|
||||||
from sphinx.locale import _
|
|
||||||
from sphinx.roles import XRefRole
|
|
||||||
from sphinx.util import logging
|
|
||||||
from sphinx.util.nodes import make_refnode
|
|
||||||
|
|
||||||
__version__ = '0.3.0'
|
|
||||||
|
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
|
||||||
|
|
||||||
|
|
||||||
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 __cal__(self, typ, rawtext, text, lineno, inliner,
|
|
||||||
options=None, content=None):
|
|
||||||
if content is None:
|
|
||||||
content = []
|
|
||||||
if options is None:
|
|
||||||
options = {}
|
|
||||||
try:
|
|
||||||
Network(text)
|
|
||||||
except ValueError as e:
|
|
||||||
env = inliner.document.settings.env
|
|
||||||
logger.warning("invalid ip address/range %s" % text, location=(env.docname, lineno))
|
|
||||||
return [nodes.literal(text, text), []]
|
|
||||||
return super(IPXRefRole, self).__call__(
|
|
||||||
typ, rawtext, text, lineno, inliner, options, content)
|
|
||||||
|
|
||||||
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):
|
|
||||||
try:
|
|
||||||
node['typ'] = self.method
|
|
||||||
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),
|
|
||||||
]
|
|
||||||
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, '', None),
|
|
||||||
('single', self.get_index_text(), name, '', None)
|
|
||||||
])
|
|
||||||
|
|
||||||
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 _('IPv4 address range ')
|
|
||||||
|
|
||||||
def get_index_text(self):
|
|
||||||
return "%s; %s" % (_('IPv4 range'), self.rangespec)
|
|
||||||
|
|
||||||
|
|
||||||
class IPv6Range(IPRange):
|
|
||||||
typ = 'v6range'
|
|
||||||
|
|
||||||
def get_prefix_title(self):
|
|
||||||
return _('IPv6 address range ')
|
|
||||||
|
|
||||||
def get_index_text(self):
|
|
||||||
return "%s; %s" % (_('IPv6 range'), self.rangespec)
|
|
||||||
|
|
||||||
|
|
||||||
class IPDomain(Domain):
|
|
||||||
"""
|
|
||||||
IP address and range domain.
|
|
||||||
"""
|
|
||||||
name = 'ip'
|
|
||||||
label = 'IP addresses and ranges.'
|
|
||||||
|
|
||||||
object_types = {
|
|
||||||
'v4': ObjType(_('v4'), 'v4', 'obj'),
|
|
||||||
'v6': ObjType(_('v6'), 'v6', 'obj'),
|
|
||||||
'v4range': ObjType(_('v4range'), 'v4range', 'obj'),
|
|
||||||
'v6range': ObjType(_('v6range'), 'v6range', 'obj'),
|
|
||||||
}
|
|
||||||
|
|
||||||
directives = {
|
|
||||||
'v4range': IPv4Range,
|
|
||||||
'v6range': IPv6Range,
|
|
||||||
}
|
|
||||||
|
|
||||||
roles = {
|
|
||||||
'v4': IPXRefRole('v4', _('IPv4 address')),
|
|
||||||
'v6': IPXRefRole('v6', _('IPv6 address')),
|
|
||||||
'v4range': IPXRefRole('v4range', _('IPv4 range')),
|
|
||||||
'v6range': IPXRefRole('v6range', _('IPv6 range')),
|
|
||||||
}
|
|
||||||
|
|
||||||
initial_data = {
|
|
||||||
'v4': {},
|
|
||||||
'v6': {},
|
|
||||||
'v4range': {},
|
|
||||||
'v6range': {},
|
|
||||||
'ips': [],
|
|
||||||
}
|
|
||||||
|
|
||||||
def clear_doc(self, docname):
|
|
||||||
to_remove = []
|
|
||||||
for key, value in self.data['v4range'].items():
|
|
||||||
if docname == value[0]:
|
|
||||||
to_remove.append(key)
|
|
||||||
for key in to_remove:
|
|
||||||
del self.data['v4range'][key]
|
|
||||||
|
|
||||||
to_remove = []
|
|
||||||
for key, value in self.data['v6range'].items():
|
|
||||||
if docname == value[0]:
|
|
||||||
to_remove.append(key)
|
|
||||||
for key in to_remove:
|
|
||||||
del self.data['v6range'][key]
|
|
||||||
self.data['ips'] = [
|
|
||||||
item for item in self.data['ips'] if item['docname'] != docname
|
|
||||||
]
|
|
||||||
|
|
||||||
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(item):
|
|
||||||
return Network(item).ip
|
|
||||||
|
|
||||||
|
|
||||||
def create_table_row(rowdata):
|
|
||||||
row = nodes.row()
|
|
||||||
for cell in rowdata:
|
|
||||||
entry = nodes.entry()
|
|
||||||
row += entry
|
|
||||||
entry += cell
|
|
||||||
return row
|
|
||||||
|
|
||||||
|
|
||||||
def process_ip_nodes(app, doctree, fromdocname):
|
|
||||||
env = app.builder.env
|
|
||||||
domaindata = env.domaindata[IPDomain.name]
|
|
||||||
|
|
||||||
header = (_('IP address'), _('Used by'))
|
|
||||||
colwidths = (1, 3)
|
|
||||||
|
|
||||||
for node in doctree.traverse(ip_range):
|
|
||||||
content = []
|
|
||||||
net = Network(node['rangespec'])
|
|
||||||
ips = {}
|
|
||||||
for key, value in [
|
|
||||||
(ip_info['ip'], ip_info) for ip_info in
|
|
||||||
domaindata['ips']
|
|
||||||
]:
|
|
||||||
try:
|
|
||||||
if not key in net:
|
|
||||||
continue
|
|
||||||
except ValueError as e:
|
|
||||||
logger.info("invalid IP address info %s", e.args)
|
|
||||||
continue
|
|
||||||
addrlist = ips.get(key, [])
|
|
||||||
addrlist.append(value)
|
|
||||||
ips[key] = addrlist
|
|
||||||
if ips:
|
|
||||||
table = nodes.table()
|
|
||||||
tgroup = nodes.tgroup(cols=len(header))
|
|
||||||
table += tgroup
|
|
||||||
for colwidth in colwidths:
|
|
||||||
tgroup += nodes.colspec(colwidth=colwidth)
|
|
||||||
thead = nodes.thead()
|
|
||||||
tgroup += thead
|
|
||||||
thead += create_table_row([
|
|
||||||
nodes.paragraph(text=label) for label in header])
|
|
||||||
tbody = nodes.tbody()
|
|
||||||
tgroup += tbody
|
|
||||||
for ip, ip_info in [
|
|
||||||
(ip, ips[ip]) for ip in sorted(ips, key=sort_ip)
|
|
||||||
]:
|
|
||||||
para = nodes.paragraph()
|
|
||||||
para += nodes.literal('', ip)
|
|
||||||
refnode = nodes.paragraph()
|
|
||||||
refuris = set()
|
|
||||||
refnodes = []
|
|
||||||
for item in ip_info:
|
|
||||||
ids = ip_object_anchor(item['typ'], item['ip'])
|
|
||||||
if ids not in para['ids']:
|
|
||||||
para['ids'].append(ids)
|
|
||||||
|
|
||||||
domaindata[item['typ']][ids] = (fromdocname, '')
|
|
||||||
newnode = nodes.reference('', '', internal=True)
|
|
||||||
try:
|
|
||||||
newnode['refuri'] = app.builder.get_relative_uri(
|
|
||||||
fromdocname, item['docname'])
|
|
||||||
if newnode['refuri'] in refuris:
|
|
||||||
continue
|
|
||||||
refuris.add(newnode['refuri'])
|
|
||||||
except NoUri:
|
|
||||||
pass
|
|
||||||
title = env.titles[item['docname']]
|
|
||||||
innernode = nodes.Text(title.astext())
|
|
||||||
newnode.append(innernode)
|
|
||||||
refnodes.append(newnode)
|
|
||||||
for count in range(len(refnodes)):
|
|
||||||
refnode.append(refnodes[count])
|
|
||||||
if count < len(refnodes) - 1:
|
|
||||||
refnode.append(nodes.Text(", "))
|
|
||||||
tbody += create_table_row([para, refnode])
|
|
||||||
content.append(table)
|
|
||||||
else:
|
|
||||||
para = nodes.paragraph(_('No IP addresses in this range'))
|
|
||||||
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__}
|
|
438
jandd/sphinxext/ip/__init__.py
Normal file
438
jandd/sphinxext/ip/__init__.py
Normal file
|
@ -0,0 +1,438 @@
|
||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
"""
|
||||||
|
jandd.sphinxext.ip
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The IP domain.
|
||||||
|
|
||||||
|
:copyright: Copyright (c) Jan Dittberner
|
||||||
|
:license: GPLv3+, see COPYING file for details.
|
||||||
|
"""
|
||||||
|
__version__ = "0.6.1"
|
||||||
|
|
||||||
|
import ipaddress
|
||||||
|
from collections import defaultdict
|
||||||
|
from typing import Iterable, List, Optional, Tuple, Any, cast
|
||||||
|
|
||||||
|
from docutils import nodes
|
||||||
|
from docutils.nodes import Element
|
||||||
|
from sphinx import addnodes
|
||||||
|
from sphinx.addnodes import desc_signature, pending_xref
|
||||||
|
from sphinx.application import Sphinx
|
||||||
|
from sphinx.builders import Builder
|
||||||
|
from sphinx.directives import ObjectDescription
|
||||||
|
from sphinx.domains import Domain, ObjType
|
||||||
|
from sphinx.environment import BuildEnvironment
|
||||||
|
from sphinx.errors import NoUri
|
||||||
|
from sphinx.locale import _
|
||||||
|
from sphinx.roles import XRefRole
|
||||||
|
from sphinx.util import logging
|
||||||
|
from sphinx.util.nodes import make_refnode
|
||||||
|
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
|
||||||
|
class ip_range(nodes.General, nodes.Element):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
class IPRangeDirective(ObjectDescription):
|
||||||
|
"""A custom directive that describes an IP address range."""
|
||||||
|
|
||||||
|
has_content = True
|
||||||
|
required_arguments = 1
|
||||||
|
title_prefix: str = ""
|
||||||
|
range_spec: str = ""
|
||||||
|
|
||||||
|
def get_title_prefix(self) -> str:
|
||||||
|
return self.title_prefix
|
||||||
|
|
||||||
|
def handle_signature(self, sig: str, sig_node: desc_signature) -> str:
|
||||||
|
sig_node += addnodes.desc_name(
|
||||||
|
text="{} {}".format(self.get_title_prefix(), sig)
|
||||||
|
)
|
||||||
|
self.range_spec = sig
|
||||||
|
return sig
|
||||||
|
|
||||||
|
def transform_content(self, content_node: addnodes.desc_content) -> None:
|
||||||
|
ip_range_node = ip_range()
|
||||||
|
ip_range_node["range_spec"] = self.range_spec
|
||||||
|
content_node += ip_range_node
|
||||||
|
|
||||||
|
|
||||||
|
class IPV4RangeDirective(IPRangeDirective):
|
||||||
|
title_prefix = _("IPv4 range")
|
||||||
|
|
||||||
|
def add_target_and_index(self, name, sig: str, sig_node: desc_signature) -> None:
|
||||||
|
anchor = "ip-ipv4range-{0}".format(sig)
|
||||||
|
sig_node["ids"].append(anchor)
|
||||||
|
ips = cast(IPDomain, self.env.get_domain("ip"))
|
||||||
|
ips.add_ip4_range(sig)
|
||||||
|
idx_text = "{}; {}".format(self.title_prefix, name)
|
||||||
|
self.indexnode["entries"] = [
|
||||||
|
("single", idx_text, anchor, "", None),
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
class IPV6RangeDirective(IPRangeDirective):
|
||||||
|
title_prefix = _("IPv6 range")
|
||||||
|
|
||||||
|
def add_target_and_index(self, name, sig: str, signode: desc_signature) -> None:
|
||||||
|
anchor = "ip-ipv6range-{0}".format(sig)
|
||||||
|
signode["ids"].append(anchor)
|
||||||
|
ips = cast(IPDomain, self.env.get_domain("ip"))
|
||||||
|
ips.add_ip6_range(sig)
|
||||||
|
idx_text = "{}; {}".format(self.title_prefix, name)
|
||||||
|
self.indexnode["entries"] = [
|
||||||
|
("single", idx_text, anchor, "", None),
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
class IPXRefRole(XRefRole):
|
||||||
|
def __init__(self, index_type):
|
||||||
|
self.index_type = index_type
|
||||||
|
super().__init__()
|
||||||
|
|
||||||
|
def process_link(
|
||||||
|
self,
|
||||||
|
env: BuildEnvironment,
|
||||||
|
refnode: nodes.Element,
|
||||||
|
has_explicit_title: bool,
|
||||||
|
title: str,
|
||||||
|
target: str,
|
||||||
|
) -> Tuple[str, str]:
|
||||||
|
refnode.attributes.update(env.ref_context)
|
||||||
|
|
||||||
|
ips = cast(IPDomain, env.get_domain("ip"))
|
||||||
|
if refnode["reftype"] == "v4":
|
||||||
|
ips.add_ip4_address_reference(target)
|
||||||
|
elif refnode["reftype"] == "v6":
|
||||||
|
ips.add_ip6_address_reference(target)
|
||||||
|
elif refnode["reftype"] == "v4range":
|
||||||
|
ips.add_ip4_range_reference(target)
|
||||||
|
elif refnode["reftype"] == "v6range":
|
||||||
|
ips.add_ip6_range_reference(target)
|
||||||
|
|
||||||
|
return title, target
|
||||||
|
|
||||||
|
def result_nodes(
|
||||||
|
self,
|
||||||
|
document: nodes.document,
|
||||||
|
env: BuildEnvironment,
|
||||||
|
node: nodes.Element,
|
||||||
|
is_ref: bool,
|
||||||
|
) -> Tuple[List[nodes.Node], List[nodes.system_message]]:
|
||||||
|
node_list, message = super().result_nodes(document, env, node, is_ref)
|
||||||
|
|
||||||
|
ip = cast(IPDomain, env.get_domain("ip"))
|
||||||
|
if self.reftype in ["v4", "v6"] and self.target not in ip.data["ip_dict"]:
|
||||||
|
return node_list, message
|
||||||
|
if (
|
||||||
|
self.reftype in ["v4range", "v6range"]
|
||||||
|
and self.target not in ip.data["ranges"]
|
||||||
|
):
|
||||||
|
return node_list, message
|
||||||
|
|
||||||
|
index_node = addnodes.index()
|
||||||
|
target_id = "ip-{}-{}".format(self.reftype, env.new_serialno("index"))
|
||||||
|
|
||||||
|
if self.reftype in ["v4", "v6"]:
|
||||||
|
ip.add_ip_address_anchor(self.target, env.docname, target_id)
|
||||||
|
|
||||||
|
target_node = nodes.target("", "", ids=[target_id])
|
||||||
|
doc_title = next(d for d in document.findall(nodes.title)).astext()
|
||||||
|
|
||||||
|
node_text = node.astext()
|
||||||
|
|
||||||
|
idx_text = "{}; {}".format(node_text, doc_title)
|
||||||
|
idx_text_2 = "{}; {}".format(self.index_type, node.astext())
|
||||||
|
index_node["entries"] = [
|
||||||
|
("single", idx_text, target_id, "", None),
|
||||||
|
("single", idx_text_2, target_id, "", None),
|
||||||
|
]
|
||||||
|
|
||||||
|
node_list.insert(0, target_node)
|
||||||
|
node_list.insert(0, index_node)
|
||||||
|
return node_list, message
|
||||||
|
|
||||||
|
|
||||||
|
class IPDomain(Domain):
|
||||||
|
"""Custom domain for IP addresses and ranges."""
|
||||||
|
|
||||||
|
def merge_domaindata(self, docnames: list[str], otherdata: dict) -> None:
|
||||||
|
# TODO: implement merge_domaindata
|
||||||
|
print(
|
||||||
|
f"merge_domaindata called for docnames: {docnames} with otherdata: {otherdata}"
|
||||||
|
)
|
||||||
|
|
||||||
|
def resolve_any_xref(
|
||||||
|
self,
|
||||||
|
env: BuildEnvironment,
|
||||||
|
fromdocname: str,
|
||||||
|
builder: Builder,
|
||||||
|
target: str,
|
||||||
|
node: pending_xref,
|
||||||
|
contnode: Element,
|
||||||
|
) -> list[tuple[str, Element]]:
|
||||||
|
# TODO: implement resolve_any_xref
|
||||||
|
print("resolve_any_xref called")
|
||||||
|
return []
|
||||||
|
|
||||||
|
name = "ip"
|
||||||
|
label = "IP addresses and ranges."
|
||||||
|
|
||||||
|
object_types = {
|
||||||
|
"v4": ObjType(_("v4"), "v4", "obj"),
|
||||||
|
"v6": ObjType(_("v6"), "v6", "obj"),
|
||||||
|
"v4range": ObjType(_("v4range"), "v4range", "obj"),
|
||||||
|
"v6range": ObjType(_("v6range"), "v6range", "obj"),
|
||||||
|
}
|
||||||
|
|
||||||
|
directives = {
|
||||||
|
"v4range": IPV4RangeDirective,
|
||||||
|
"v6range": IPV6RangeDirective,
|
||||||
|
}
|
||||||
|
|
||||||
|
roles = {
|
||||||
|
"v4": IPXRefRole("IPv4 address"),
|
||||||
|
"v6": IPXRefRole("IPv6 address"),
|
||||||
|
"v4range": IPXRefRole("IPv4 range"),
|
||||||
|
"v6range": IPXRefRole("IPv6 range"),
|
||||||
|
}
|
||||||
|
|
||||||
|
initial_data = {
|
||||||
|
"range_nodes": [],
|
||||||
|
"ip_refs": defaultdict(list),
|
||||||
|
"range_refs": [],
|
||||||
|
"ranges": defaultdict(list),
|
||||||
|
"ip_dict": {},
|
||||||
|
}
|
||||||
|
|
||||||
|
def get_full_qualified_name(self, node: nodes.Element) -> Optional[str]:
|
||||||
|
return "{}.{}".format("ip", node)
|
||||||
|
|
||||||
|
def get_objects(self) -> Iterable[Tuple[str, str, str, str, str, int]]:
|
||||||
|
for obj in self.data["range_nodes"]:
|
||||||
|
yield obj
|
||||||
|
|
||||||
|
def add_ip4_range(self, sig: str):
|
||||||
|
logger.debug("add_ip4_range: %s", sig)
|
||||||
|
self._add_ip_range("v4", sig)
|
||||||
|
|
||||||
|
def add_ip6_range(self, sig: str):
|
||||||
|
logger.debug("add_ip6_range: %s", sig)
|
||||||
|
self._add_ip_range("v6", sig)
|
||||||
|
|
||||||
|
def _add_ip_range(self, family: str, sig: str):
|
||||||
|
name = "ip{}range.{}".format(family, sig)
|
||||||
|
anchor = "ip-ip{}range-{}".format(family, sig)
|
||||||
|
try:
|
||||||
|
new_ip_range = ipaddress.ip_network(sig)
|
||||||
|
self.data["range_nodes"].append(
|
||||||
|
(name, family, sig, self.env.docname, anchor, 0)
|
||||||
|
)
|
||||||
|
self.data["ranges"][sig].append((new_ip_range, self.env.docname, anchor))
|
||||||
|
except ValueError as e:
|
||||||
|
logger.error("invalid ip range address '%s': %s", sig, e)
|
||||||
|
|
||||||
|
def add_ip4_address_reference(self, ip_address: str):
|
||||||
|
logger.debug("add_ip4_address_reference")
|
||||||
|
self._add_ip_address_reference("v4", ip_address)
|
||||||
|
|
||||||
|
def add_ip6_address_reference(self, ip_address: str):
|
||||||
|
logger.debug("add_ip4_address_reference")
|
||||||
|
self._add_ip_address_reference("v6", ip_address)
|
||||||
|
|
||||||
|
def _add_ip_address_reference(self, family, sig):
|
||||||
|
try:
|
||||||
|
self.data["ip_dict"][sig] = ipaddress.ip_address(sig)
|
||||||
|
except ValueError as e:
|
||||||
|
logger.error("invalid ip address '%s': %s", sig, e)
|
||||||
|
|
||||||
|
def add_ip_address_anchor(self, sig, docname, anchor):
|
||||||
|
try:
|
||||||
|
ip = ipaddress.ip_address(sig)
|
||||||
|
self.data["ip_refs"][sig].append((ip, docname, anchor))
|
||||||
|
except ValueError as e:
|
||||||
|
logger.error("invalid ip address '%s': %s", sig, e)
|
||||||
|
|
||||||
|
def add_ip4_range_reference(self, ip_range: str):
|
||||||
|
logger.debug("add_ip4_range_reference")
|
||||||
|
self._add_ip_range_reference("v4", ip_range)
|
||||||
|
|
||||||
|
def add_ip6_range_reference(self, ip_range: str):
|
||||||
|
logger.debug("add_ip6_address_reference")
|
||||||
|
self._add_ip_range_reference("v6", ip_range)
|
||||||
|
|
||||||
|
def _add_ip_range_reference(self, family, sig):
|
||||||
|
name = "iprange{}.{}".format(family, sig)
|
||||||
|
anchor = "ip-iprange{}-{}".format(family, sig)
|
||||||
|
try:
|
||||||
|
ip_range = ipaddress.ip_network(sig)
|
||||||
|
self.data["range_refs"].append(
|
||||||
|
(
|
||||||
|
name,
|
||||||
|
sig,
|
||||||
|
"IP{} range".format(family),
|
||||||
|
str(ip_range),
|
||||||
|
self.env.docname,
|
||||||
|
anchor,
|
||||||
|
0,
|
||||||
|
)
|
||||||
|
)
|
||||||
|
except ValueError as e:
|
||||||
|
logger.error("invalid ip range '%s': %s", sig, e)
|
||||||
|
|
||||||
|
def resolve_xref(
|
||||||
|
self,
|
||||||
|
env: BuildEnvironment,
|
||||||
|
fromdocname: str,
|
||||||
|
builder: Builder,
|
||||||
|
typ: str,
|
||||||
|
target: str,
|
||||||
|
node: pending_xref,
|
||||||
|
contnode: nodes.Element,
|
||||||
|
) -> Optional[nodes.Element]:
|
||||||
|
match = []
|
||||||
|
|
||||||
|
def address_tuple(docname, anchor, ip_range: Any) -> Tuple[str, str, str]:
|
||||||
|
return (
|
||||||
|
docname,
|
||||||
|
anchor,
|
||||||
|
_("IPv{0} range {1}".format(ip_range.version, ip_range.compressed)),
|
||||||
|
)
|
||||||
|
|
||||||
|
if typ in ("v4", "v6"):
|
||||||
|
# reference to IP range
|
||||||
|
if target not in self.data["ip_dict"]:
|
||||||
|
# invalid ip address
|
||||||
|
raise NoUri(target)
|
||||||
|
match = [
|
||||||
|
address_tuple(docname, anchor, ip_range)
|
||||||
|
for ip_range, docname, anchor in [
|
||||||
|
r
|
||||||
|
for range_nodes in self.data["ranges"].values()
|
||||||
|
for r in range_nodes
|
||||||
|
]
|
||||||
|
if self.data["ip_dict"][target] in ip_range
|
||||||
|
]
|
||||||
|
elif typ in ("v4range", "v6range"):
|
||||||
|
if target in self.data["ranges"]:
|
||||||
|
match = [
|
||||||
|
address_tuple(docname, anchor, ip_range)
|
||||||
|
for ip_range, docname, anchor in [
|
||||||
|
range_nodes for range_nodes in self.data["ranges"][target]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
if len(match) > 0:
|
||||||
|
todocname = match[0][0]
|
||||||
|
targ = match[0][1]
|
||||||
|
title = match[0][2]
|
||||||
|
|
||||||
|
return make_refnode(builder, fromdocname, todocname, targ, contnode, title)
|
||||||
|
else:
|
||||||
|
logger.error("found no link target for %s", target)
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def process_ip_nodes(app: Sphinx, doctree: nodes.Node, fromdocname: str):
|
||||||
|
env = app.builder.env
|
||||||
|
ips = env.get_domain(IPDomain.name)
|
||||||
|
|
||||||
|
header = (_("IP address"), _("Used by"))
|
||||||
|
column_widths = (2, 5)
|
||||||
|
|
||||||
|
for node in doctree.findall(ip_range):
|
||||||
|
content = []
|
||||||
|
net = ipaddress.ip_network(node["range_spec"], strict=False)
|
||||||
|
addresses = defaultdict(list)
|
||||||
|
for ip_address_sig, refs in ips.data["ip_refs"].items():
|
||||||
|
for ip_address, to_doc_name, anchor in refs:
|
||||||
|
if ip_address in net:
|
||||||
|
addresses[ip_address_sig].append((ip_address, to_doc_name, anchor))
|
||||||
|
logger.debug(
|
||||||
|
"found %s in network %s on %s",
|
||||||
|
ip_address_sig,
|
||||||
|
net.compressed,
|
||||||
|
to_doc_name,
|
||||||
|
)
|
||||||
|
if addresses:
|
||||||
|
table = nodes.table()
|
||||||
|
table.attributes["classes"].append("indextable")
|
||||||
|
table.attributes["align"] = "left"
|
||||||
|
|
||||||
|
tgroup = nodes.tgroup(cols=len(header))
|
||||||
|
table += tgroup
|
||||||
|
for column_width in column_widths:
|
||||||
|
tgroup += nodes.colspec(colwidth=column_width)
|
||||||
|
|
||||||
|
thead = nodes.thead()
|
||||||
|
tgroup += thead
|
||||||
|
thead += create_table_row([nodes.paragraph(text=label) for label in header])
|
||||||
|
|
||||||
|
tbody = nodes.tbody()
|
||||||
|
tgroup += tbody
|
||||||
|
|
||||||
|
for ip_address_sig, ip_info in [
|
||||||
|
(key, addresses[key]) for key in sorted(addresses, key=sort_by_ip)
|
||||||
|
]:
|
||||||
|
para = nodes.paragraph()
|
||||||
|
para += nodes.literal("", ip_info[0][0].compressed)
|
||||||
|
|
||||||
|
ref_node = nodes.paragraph()
|
||||||
|
ref_nodes = []
|
||||||
|
referenced_docs = set()
|
||||||
|
|
||||||
|
for item in ip_info:
|
||||||
|
ip_address, to_doc_name, anchor = item
|
||||||
|
if to_doc_name in referenced_docs:
|
||||||
|
continue
|
||||||
|
referenced_docs.add(to_doc_name)
|
||||||
|
|
||||||
|
title = env.titles[to_doc_name]
|
||||||
|
inner_node = nodes.Text(title.astext())
|
||||||
|
new_node = make_refnode(
|
||||||
|
app.builder,
|
||||||
|
fromdocname,
|
||||||
|
to_doc_name,
|
||||||
|
anchor,
|
||||||
|
inner_node,
|
||||||
|
title.astext(),
|
||||||
|
)
|
||||||
|
|
||||||
|
ref_nodes.append(new_node)
|
||||||
|
for count in range(len(ref_nodes)):
|
||||||
|
ref_node.append(ref_nodes[count])
|
||||||
|
if count < len(ref_nodes) - 1:
|
||||||
|
ref_node.append(nodes.Text(", "))
|
||||||
|
tbody += create_table_row([para, ref_node])
|
||||||
|
content.append(table)
|
||||||
|
else:
|
||||||
|
para = nodes.paragraph(_("No IP addresses in this range"))
|
||||||
|
content.append(para)
|
||||||
|
|
||||||
|
node.replace_self(content)
|
||||||
|
|
||||||
|
|
||||||
|
def create_table_row(rowdata):
|
||||||
|
row = nodes.row()
|
||||||
|
for cell in rowdata:
|
||||||
|
entry = nodes.entry()
|
||||||
|
row += entry
|
||||||
|
entry += cell
|
||||||
|
return row
|
||||||
|
|
||||||
|
|
||||||
|
def sort_by_ip(item):
|
||||||
|
return ipaddress.ip_address(item)
|
||||||
|
|
||||||
|
|
||||||
|
def setup(app: Sphinx):
|
||||||
|
app.add_domain(IPDomain)
|
||||||
|
app.connect("doctree-resolved", process_ip_nodes)
|
||||||
|
return {
|
||||||
|
"version": __version__,
|
||||||
|
"env_version": 4,
|
||||||
|
"parallel_read_safe": True,
|
||||||
|
"parallel_write_safe": True,
|
||||||
|
}
|
9
pyproject.toml
Normal file
9
pyproject.toml
Normal file
|
@ -0,0 +1,9 @@
|
||||||
|
[build-system]
|
||||||
|
requires = [
|
||||||
|
"setuptools >= 35.0.2",
|
||||||
|
"setuptools_scm[toml] >= 5.0",
|
||||||
|
"wheel >= 0.29.0"
|
||||||
|
]
|
||||||
|
build-backend = "setuptools.build_meta"
|
||||||
|
|
||||||
|
[tool.setuptools_scm]
|
35
setup.cfg
35
setup.cfg
|
@ -1,13 +1,34 @@
|
||||||
[egg_info]
|
|
||||||
tag_build = dev
|
|
||||||
tag_date = true
|
|
||||||
|
|
||||||
[aliases]
|
|
||||||
release = egg_info -RDb ''
|
|
||||||
|
|
||||||
[coverage:run]
|
[coverage:run]
|
||||||
branch = true
|
branch = true
|
||||||
source = jandd.sphinxext.ip
|
source = jandd.sphinxext.ip
|
||||||
|
|
||||||
[coverage:report]
|
[coverage:report]
|
||||||
show_missing = true
|
show_missing = true
|
||||||
|
|
||||||
|
[metadata]
|
||||||
|
name = jandd.sphinxext.ip
|
||||||
|
description = IP address extension for Sphinx
|
||||||
|
long_description = file: README.rst, CHANGES.rst
|
||||||
|
long_description_content_type = text/x-rst
|
||||||
|
url = https://pypi.org/project/jandd.sphinxext.ip/
|
||||||
|
author = Jan Dittberner
|
||||||
|
author_email = jan@dittberner.info
|
||||||
|
keywords = sphinx, extension, IP
|
||||||
|
license = GPLv3+
|
||||||
|
license_files = COPYING
|
||||||
|
platforms = any
|
||||||
|
version = 0.6.1
|
||||||
|
classifiers =
|
||||||
|
Development Status :: 5 - Production/Stable
|
||||||
|
Framework :: Sphinx :: Extension
|
||||||
|
License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
|
||||||
|
Programming Language :: Python :: 3
|
||||||
|
Topic :: Documentation
|
||||||
|
Topic :: Internet
|
||||||
|
|
||||||
|
[options]
|
||||||
|
zip_safe = False
|
||||||
|
include_package_data = True
|
||||||
|
packages = find_namespace:
|
||||||
|
install_requires =
|
||||||
|
Sphinx >= 5
|
||||||
|
|
43
setup.py
43
setup.py
|
@ -1,42 +1,3 @@
|
||||||
#!/usr/bin/env python3
|
from setuptools import setup
|
||||||
|
|
||||||
from setuptools import setup, find_packages
|
setup()
|
||||||
|
|
||||||
version = '0.3.0'
|
|
||||||
|
|
||||||
with open('README.rst') as readme:
|
|
||||||
description = readme.read() + "\n\n"
|
|
||||||
|
|
||||||
with open('CHANGES.rst') as changes:
|
|
||||||
description += changes.read()
|
|
||||||
|
|
||||||
requires = ['Sphinx>=1.4', 'ipcalc>=1.99']
|
|
||||||
tests_requires = ['path.py>=8.2.1']
|
|
||||||
|
|
||||||
|
|
||||||
setup(
|
|
||||||
author="Jan Dittberner",
|
|
||||||
author_email="jan@dittberner.info",
|
|
||||||
description="IP address extension for Sphinx",
|
|
||||||
long_description=description,
|
|
||||||
include_package_data=True,
|
|
||||||
install_requires=requires,
|
|
||||||
keywords="sphinx extension IP",
|
|
||||||
license="GPLv3+",
|
|
||||||
url="https://pypi.python.org/pypi/jandd.sphinxext.ip",
|
|
||||||
name="jandd.sphinxext.ip",
|
|
||||||
namespace_packages=['jandd', 'jandd.sphinxext'],
|
|
||||||
packages=find_packages(),
|
|
||||||
platforms='any',
|
|
||||||
tests_requires=tests_requires,
|
|
||||||
version=version,
|
|
||||||
zip_safe=False,
|
|
||||||
classifiers=[
|
|
||||||
"Development Status :: 4 - Beta",
|
|
||||||
"Framework :: Sphinx :: Extension",
|
|
||||||
"License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
|
|
||||||
"Programming Language :: Python :: 3",
|
|
||||||
"Topic :: Documentation",
|
|
||||||
"Topic :: Internet",
|
|
||||||
],
|
|
||||||
)
|
|
||||||
|
|
|
@ -12,52 +12,52 @@
|
||||||
#
|
#
|
||||||
# All configuration values have a default; values that are commented out
|
# All configuration values have a default; values that are commented out
|
||||||
# serve to show the default.
|
# serve to show the default.
|
||||||
|
import os
|
||||||
#import sys
|
import sys
|
||||||
#import os
|
from typing import Dict
|
||||||
|
|
||||||
# If extensions (or modules to document with autodoc) are in another directory,
|
# If extensions (or modules to document with autodoc) are in another directory,
|
||||||
# add these directories to sys.path here. If the directory is relative to the
|
# add these directories to sys.path here. If the directory is relative to the
|
||||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
#sys.path.insert(0, os.path.abspath('..'))
|
sys.path.insert(0, os.path.abspath(os.path.join("..", "..")))
|
||||||
|
|
||||||
# -- General configuration ------------------------------------------------
|
# -- General configuration ------------------------------------------------
|
||||||
|
|
||||||
# If your documentation needs a minimal Sphinx version, state it here.
|
# If your documentation needs a minimal Sphinx version, state it here.
|
||||||
#needs_sphinx = '1.0'
|
# needs_sphinx = '1.0'
|
||||||
|
|
||||||
# Add any Sphinx extension module names here, as strings. They can be
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
# ones.
|
# ones.
|
||||||
extensions = ['jandd.sphinxext.ip']
|
extensions = ["jandd.sphinxext.ip"]
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
templates_path = ['_templates']
|
templates_path = ["_templates"]
|
||||||
|
|
||||||
# The suffix(es) of source filenames.
|
# The suffix(es) of source filenames.
|
||||||
# You can specify multiple suffix as a list of string:
|
# You can specify multiple suffix as a list of string:
|
||||||
# source_suffix = ['.rst', '.md']
|
# source_suffix = ['.rst', '.md']
|
||||||
source_suffix = '.rst'
|
source_suffix = ".rst"
|
||||||
|
|
||||||
# The encoding of source files.
|
# The encoding of source files.
|
||||||
#source_encoding = 'utf-8-sig'
|
# source_encoding = 'utf-8-ip_range'
|
||||||
|
|
||||||
# The master toctree document.
|
# The master toctree document.
|
||||||
master_doc = 'index'
|
master_doc = "index"
|
||||||
|
|
||||||
# General information about the project.
|
# General information about the project.
|
||||||
project = 'Sphinxext IP Tests'
|
project = "Sphinxext IP Tests"
|
||||||
copyright = '2016, Jan Dittberner'
|
copyright = "2016-2023, Jan Dittberner"
|
||||||
author = 'Jan Dittberner'
|
author = "Jan Dittberner"
|
||||||
|
|
||||||
# The version info for the project you're documenting, acts as replacement for
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
# |version| and |release|, also used in various other places throughout the
|
# |version| and |release|, also used in various other places throughout the
|
||||||
# built documents.
|
# built documents.
|
||||||
#
|
#
|
||||||
# The short X.Y version.
|
# The short X.Y version.
|
||||||
version = '0.1.0'
|
version = "0.6.1"
|
||||||
# The full version, including alpha/beta/rc tags.
|
# The full version, including alpha/beta/rc tags.
|
||||||
release = '0.1.0'
|
release = version
|
||||||
|
|
||||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
# for a list of supported languages.
|
# for a list of supported languages.
|
||||||
|
@ -68,186 +68,187 @@ language = None
|
||||||
|
|
||||||
# There are two options for replacing |today|: either, you set today to some
|
# There are two options for replacing |today|: either, you set today to some
|
||||||
# non-false value, then it is used:
|
# non-false value, then it is used:
|
||||||
#today = ''
|
# today = ''
|
||||||
# Else, today_fmt is used as the format for a strftime call.
|
# Else, today_fmt is used as the format for a strftime call.
|
||||||
#today_fmt = '%B %d, %Y'
|
# today_fmt = '%B %d, %Y'
|
||||||
|
|
||||||
# List of patterns, relative to source directory, that match files and
|
# List of patterns, relative to source directory, that match files and
|
||||||
# directories to ignore when looking for source files.
|
# directories to ignore when looking for source files.
|
||||||
# This patterns also effect to html_static_path and html_extra_path
|
# This patterns also effect to html_static_path and html_extra_path
|
||||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
|
||||||
|
|
||||||
# The reST default role (used for this markup: `text`) to use for all
|
# The reST default role (used for this markup: `text`) to use for all
|
||||||
# documents.
|
# documents.
|
||||||
#default_role = None
|
# default_role = None
|
||||||
|
|
||||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||||
#add_function_parentheses = True
|
# add_function_parentheses = True
|
||||||
|
|
||||||
# If true, the current module name will be prepended to all description
|
# If true, the current module name will be prepended to all description
|
||||||
# unit titles (such as .. function::).
|
# unit titles (such as .. function::).
|
||||||
#add_module_names = True
|
# add_module_names = True
|
||||||
|
|
||||||
# If true, sectionauthor and moduleauthor directives will be shown in the
|
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||||
# output. They are ignored by default.
|
# output. They are ignored by default.
|
||||||
#show_authors = False
|
# show_authors = False
|
||||||
|
|
||||||
# The name of the Pygments (syntax highlighting) style to use.
|
# The name of the Pygments (syntax highlighting) style to use.
|
||||||
pygments_style = 'sphinx'
|
pygments_style = "sphinx"
|
||||||
|
|
||||||
# A list of ignored prefixes for module index sorting.
|
# A list of ignored prefixes for module index sorting.
|
||||||
#modindex_common_prefix = []
|
# modindex_common_prefix = []
|
||||||
|
|
||||||
# If true, keep warnings as "system message" paragraphs in the built documents.
|
# If true, keep warnings as "system message" paragraphs in the built documents.
|
||||||
#keep_warnings = False
|
# keep_warnings = False
|
||||||
|
|
||||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||||
todo_include_todos = False
|
todo_include_todos = False
|
||||||
|
|
||||||
|
|
||||||
# -- Options for HTML output ----------------------------------------------
|
# -- Options for HTML output ----------------------------------------------
|
||||||
|
|
||||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
# a list of builtin themes.
|
# a list of builtin themes.
|
||||||
html_theme = 'alabaster'
|
html_theme = "alabaster"
|
||||||
|
|
||||||
# Theme options are theme-specific and customize the look and feel of a theme
|
# Theme options are theme-specific and customize the look and feel of a theme
|
||||||
# further. For a list of options available for each theme, see the
|
# further. For a list of options available for each theme, see the
|
||||||
# documentation.
|
# documentation.
|
||||||
#html_theme_options = {}
|
# html_theme_options = {}
|
||||||
|
|
||||||
# Add any paths that contain custom themes here, relative to this directory.
|
# Add any paths that contain custom themes here, relative to this directory.
|
||||||
#html_theme_path = []
|
# html_theme_path = []
|
||||||
|
|
||||||
# The name for this set of Sphinx documents.
|
# The name for this set of Sphinx documents.
|
||||||
# "<project> v<release> documentation" by default.
|
# "<project> v<release> documentation" by default.
|
||||||
#html_title = 'Sphinxext IP Tests v0.1.0'
|
# html_title = 'Sphinxext IP Tests v0.1.0'
|
||||||
|
|
||||||
# A shorter title for the navigation bar. Default is the same as html_title.
|
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||||
#html_short_title = None
|
# html_short_title = None
|
||||||
|
|
||||||
# The name of an image file (relative to this directory) to place at the top
|
# The name of an image file (relative to this directory) to place at the top
|
||||||
# of the sidebar.
|
# of the sidebar.
|
||||||
#html_logo = None
|
# html_logo = None
|
||||||
|
|
||||||
# The name of an image file (relative to this directory) to use as a favicon of
|
# The name of an image file (relative to this directory) to use as a favicon of
|
||||||
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||||
# pixels large.
|
# pixels large.
|
||||||
#html_favicon = None
|
# html_favicon = None
|
||||||
|
|
||||||
# Add any paths that contain custom static files (such as style sheets) here,
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
# relative to this directory. They are copied after the builtin static files,
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
html_static_path = ['_static']
|
html_static_path = ["_static"]
|
||||||
|
|
||||||
# Add any extra paths that contain custom files (such as robots.txt or
|
# Add any extra paths that contain custom files (such as robots.txt or
|
||||||
# .htaccess) here, relative to this directory. These files are copied
|
# .htaccess) here, relative to this directory. These files are copied
|
||||||
# directly to the root of the documentation.
|
# directly to the root of the documentation.
|
||||||
#html_extra_path = []
|
# html_extra_path = []
|
||||||
|
|
||||||
# If not None, a 'Last updated on:' timestamp is inserted at every page
|
# If not None, a 'Last updated on:' timestamp is inserted at every page
|
||||||
# bottom, using the given strftime format.
|
# bottom, using the given strftime format.
|
||||||
# The empty string is equivalent to '%b %d, %Y'.
|
# The empty string is equivalent to '%b %d, %Y'.
|
||||||
#html_last_updated_fmt = None
|
# html_last_updated_fmt = None
|
||||||
|
|
||||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||||
# typographically correct entities.
|
# typographically correct entities.
|
||||||
#html_use_smartypants = True
|
# html_use_smartypants = True
|
||||||
|
|
||||||
# Custom sidebar templates, maps document names to template names.
|
# Custom sidebar templates, maps document names to template names.
|
||||||
#html_sidebars = {}
|
# html_sidebars = {}
|
||||||
|
|
||||||
# Additional templates that should be rendered to pages, maps page names to
|
# Additional templates that should be rendered to pages, maps page names to
|
||||||
# template names.
|
# template names.
|
||||||
#html_additional_pages = {}
|
# html_additional_pages = {}
|
||||||
|
|
||||||
# If false, no module index is generated.
|
# If false, no module index is generated.
|
||||||
#html_domain_indices = True
|
# html_domain_indices = True
|
||||||
|
|
||||||
# If false, no index is generated.
|
# If false, no index is generated.
|
||||||
#html_use_index = True
|
# html_use_index = True
|
||||||
|
|
||||||
# If true, the index is split into individual pages for each letter.
|
# If true, the index is split into individual pages for each letter.
|
||||||
#html_split_index = False
|
# html_split_index = False
|
||||||
|
|
||||||
# If true, links to the reST sources are added to the pages.
|
# If true, links to the reST sources are added to the pages.
|
||||||
#html_show_sourcelink = True
|
# html_show_sourcelink = True
|
||||||
|
|
||||||
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
|
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
|
||||||
#html_show_sphinx = True
|
# html_show_sphinx = True
|
||||||
|
|
||||||
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
|
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
|
||||||
#html_show_copyright = True
|
# html_show_copyright = True
|
||||||
|
|
||||||
# If true, an OpenSearch description file will be output, and all pages will
|
# If true, an OpenSearch description file will be output, and all pages will
|
||||||
# contain a <link> tag referring to it. The value of this option must be the
|
# contain a <link> tag referring to it. The value of this option must be the
|
||||||
# base URL from which the finished HTML is served.
|
# base URL from which the finished HTML is served.
|
||||||
#html_use_opensearch = ''
|
# html_use_opensearch = ''
|
||||||
|
|
||||||
# This is the file name suffix for HTML files (e.g. ".xhtml").
|
# This is the file name suffix for HTML files (e.g. ".xhtml").
|
||||||
#html_file_suffix = None
|
# html_file_suffix = None
|
||||||
|
|
||||||
# Language to be used for generating the HTML full-text search index.
|
# Language to be used for generating the HTML full-text search index.
|
||||||
# Sphinx supports the following languages:
|
# Sphinx supports the following languages:
|
||||||
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
|
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
|
||||||
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
|
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
|
||||||
#html_search_language = 'en'
|
# html_search_language = 'en'
|
||||||
|
|
||||||
# A dictionary with options for the search language support, empty by default.
|
# A dictionary with options for the search language support, empty by default.
|
||||||
# 'ja' uses this config value.
|
# 'ja' uses this config value.
|
||||||
# 'zh' user can custom change `jieba` dictionary path.
|
# 'zh' user can custom change `jieba` dictionary path.
|
||||||
#html_search_options = {'type': 'default'}
|
# html_search_options = {'type': 'default'}
|
||||||
|
|
||||||
# The name of a javascript file (relative to the configuration directory) that
|
# The name of a javascript file (relative to the configuration directory) that
|
||||||
# implements a search results scorer. If empty, the default will be used.
|
# implements a search results scorer. If empty, the default will be used.
|
||||||
#html_search_scorer = 'scorer.js'
|
# html_search_scorer = 'scorer.js'
|
||||||
|
|
||||||
# Output file base name for HTML help builder.
|
# Output file base name for HTML help builder.
|
||||||
htmlhelp_basename = 'SphinxextIPTestsdoc'
|
htmlhelp_basename = "SphinxextIPTestsdoc"
|
||||||
|
|
||||||
# -- Options for LaTeX output ---------------------------------------------
|
# -- Options for LaTeX output ---------------------------------------------
|
||||||
|
|
||||||
latex_elements = {
|
latex_elements: Dict[str, str] = {
|
||||||
# The paper size ('letterpaper' or 'a4paper').
|
# The paper size ('letterpaper' or 'a4paper').
|
||||||
#'papersize': 'letterpaper',
|
# 'papersize': 'letterpaper',
|
||||||
|
# The font size ('10pt', '11pt' or '12pt').
|
||||||
# The font size ('10pt', '11pt' or '12pt').
|
# 'pointsize': '10pt',
|
||||||
#'pointsize': '10pt',
|
# Additional stuff for the LaTeX preamble.
|
||||||
|
# 'preamble': '',
|
||||||
# Additional stuff for the LaTeX preamble.
|
# Latex figure (float) alignment
|
||||||
#'preamble': '',
|
# 'figure_align': 'htbp',
|
||||||
|
|
||||||
# Latex figure (float) alignment
|
|
||||||
#'figure_align': 'htbp',
|
|
||||||
}
|
}
|
||||||
|
|
||||||
# Grouping the document tree into LaTeX files. List of tuples
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
# (source start file, target name, title,
|
# (source start file, target name, title,
|
||||||
# author, documentclass [howto, manual, or own class]).
|
# author, documentclass [howto, manual, or own class]).
|
||||||
latex_documents = [
|
latex_documents = [
|
||||||
(master_doc, 'SphinxextIPTests.tex', 'Sphinxext IP Tests Documentation',
|
(
|
||||||
'Jan Dittberner', 'manual'),
|
master_doc,
|
||||||
|
"SphinxextIPTests.tex",
|
||||||
|
"Sphinxext IP Tests Documentation",
|
||||||
|
"Jan Dittberner",
|
||||||
|
"manual",
|
||||||
|
),
|
||||||
]
|
]
|
||||||
|
|
||||||
# The name of an image file (relative to this directory) to place at the top of
|
# The name of an image file (relative to this directory) to place at the top of
|
||||||
# the title page.
|
# the title page.
|
||||||
#latex_logo = None
|
# latex_logo = None
|
||||||
|
|
||||||
# For "manual" documents, if this is true, then toplevel headings are parts,
|
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||||
# not chapters.
|
# not chapters.
|
||||||
#latex_use_parts = False
|
# latex_use_parts = False
|
||||||
|
|
||||||
# If true, show page references after internal links.
|
# If true, show page references after internal links.
|
||||||
#latex_show_pagerefs = False
|
# latex_show_pagerefs = False
|
||||||
|
|
||||||
# If true, show URL addresses after external links.
|
# If true, show URL addresses after external links.
|
||||||
#latex_show_urls = False
|
# latex_show_urls = False
|
||||||
|
|
||||||
# Documents to append as an appendix to all manuals.
|
# Documents to append as an appendix to all manuals.
|
||||||
#latex_appendices = []
|
# latex_appendices = []
|
||||||
|
|
||||||
# If false, no module index is generated.
|
# If false, no module index is generated.
|
||||||
#latex_domain_indices = True
|
# latex_domain_indices = True
|
||||||
|
|
||||||
|
|
||||||
# -- Options for manual page output ---------------------------------------
|
# -- Options for manual page output ---------------------------------------
|
||||||
|
@ -255,12 +256,11 @@ latex_documents = [
|
||||||
# One entry per manual page. List of tuples
|
# One entry per manual page. List of tuples
|
||||||
# (source start file, name, description, authors, manual section).
|
# (source start file, name, description, authors, manual section).
|
||||||
man_pages = [
|
man_pages = [
|
||||||
(master_doc, 'sphinxextiptests', 'Sphinxext IP Tests Documentation',
|
(master_doc, "sphinxextiptests", "Sphinxext IP Tests Documentation", [author], 1)
|
||||||
[author], 1)
|
|
||||||
]
|
]
|
||||||
|
|
||||||
# If true, show URL addresses after external links.
|
# If true, show URL addresses after external links.
|
||||||
#man_show_urls = False
|
# man_show_urls = False
|
||||||
|
|
||||||
|
|
||||||
# -- Options for Texinfo output -------------------------------------------
|
# -- Options for Texinfo output -------------------------------------------
|
||||||
|
@ -269,19 +269,25 @@ man_pages = [
|
||||||
# (source start file, target name, title, author,
|
# (source start file, target name, title, author,
|
||||||
# dir menu entry, description, category)
|
# dir menu entry, description, category)
|
||||||
texinfo_documents = [
|
texinfo_documents = [
|
||||||
(master_doc, 'SphinxextIPTests', 'Sphinxext IP Tests Documentation',
|
(
|
||||||
author, 'SphinxextIPTests', 'One line description of project.',
|
master_doc,
|
||||||
'Miscellaneous'),
|
"SphinxextIPTests",
|
||||||
|
"Sphinxext IP Tests Documentation",
|
||||||
|
author,
|
||||||
|
"SphinxextIPTests",
|
||||||
|
"One line description of project.",
|
||||||
|
"Miscellaneous",
|
||||||
|
),
|
||||||
]
|
]
|
||||||
|
|
||||||
# Documents to append as an appendix to all manuals.
|
# Documents to append as an appendix to all manuals.
|
||||||
#texinfo_appendices = []
|
# texinfo_appendices = []
|
||||||
|
|
||||||
# If false, no module index is generated.
|
# If false, no module index is generated.
|
||||||
#texinfo_domain_indices = True
|
# texinfo_domain_indices = True
|
||||||
|
|
||||||
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
||||||
#texinfo_show_urls = 'footnote'
|
# texinfo_show_urls = 'footnote'
|
||||||
|
|
||||||
# If true, do not generate a @detailmenu in the "Top" node's menu.
|
# If true, do not generate a @detailmenu in the "Top" node's menu.
|
||||||
#texinfo_no_detailmenu = False
|
# texinfo_no_detailmenu = False
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
Test page 3
|
Test page 3
|
||||||
===========
|
===========
|
||||||
|
|
||||||
This page contains :ip:v6:`2001:dead:beef::1` like :doc:`testpage2` does.
|
This page contains :ip:v6:`2001:dead:beef::1` from :ip:v6range:`2001:dead:beef::/64`
|
||||||
|
like :doc:`testpage2` does.
|
||||||
|
|
20
tests/run.py
20
tests/run.py
|
@ -11,25 +11,27 @@ This script runs the jandd.sphinxext.ip unit test suite.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
import sys
|
import sys
|
||||||
from os import path
|
|
||||||
import unittest
|
import unittest
|
||||||
|
from os import path
|
||||||
|
|
||||||
|
|
||||||
def run(extra_args=[]):
|
def run(extra_args=[]):
|
||||||
sys.path.insert(0, path.join(path.dirname(__file__), path.pardir))
|
sys.path.insert(0, path.join(path.dirname(__file__), path.pardir))
|
||||||
sys.path.insert(1, path.abspath(
|
sys.path.insert(
|
||||||
path.join(path.dirname(__file__), path.pardir,
|
1,
|
||||||
'jandd', 'sphinxext', 'ip'
|
path.abspath(
|
||||||
))
|
path.join(path.dirname(__file__), path.pardir, "jandd", "sphinxext", "ip")
|
||||||
|
),
|
||||||
)
|
)
|
||||||
|
|
||||||
try:
|
try:
|
||||||
import sphinx
|
import sphinx
|
||||||
except ImportError:
|
except ImportError:
|
||||||
print("The sphinx package is needed to run the jandd.sphinxext.ip "
|
print(
|
||||||
"test suite.")
|
"The sphinx package is needed to run the jandd.sphinxext.ip " "test suite."
|
||||||
|
)
|
||||||
|
|
||||||
from .test_ip import TestIPExtension
|
from tests.test_ip import TestIPExtension
|
||||||
|
|
||||||
print("Running jandd.sphinxext.ip test suite ...")
|
print("Running jandd.sphinxext.ip test suite ...")
|
||||||
|
|
||||||
|
@ -37,5 +39,5 @@ def run(extra_args=[]):
|
||||||
unittest.TextTestRunner(verbosity=2).run(suite)
|
unittest.TextTestRunner(verbosity=2).run(suite)
|
||||||
|
|
||||||
|
|
||||||
if __name__ == '__main__':
|
if __name__ == "__main__":
|
||||||
run()
|
run()
|
||||||
|
|
|
@ -1,40 +1,41 @@
|
||||||
# -*- coding: utf-8 -*-
|
# -*- coding: utf-8 -*-
|
||||||
|
import shutil
|
||||||
from io import StringIO
|
|
||||||
from .util import TestApp, test_root
|
|
||||||
import unittest
|
import unittest
|
||||||
|
from io import StringIO
|
||||||
|
|
||||||
|
from .util import SphinxTestApplication, test_root
|
||||||
|
|
||||||
IP4_ADDRESSES = ['127.0.0.1', '192.168.0.1']
|
IP4_ADDRESSES = ["127.0.0.1", "192.168.0.1"]
|
||||||
IP6_ADDRESSES = ['::1', '2001:dead:beef::1']
|
IP6_ADDRESSES = ["::1", "2001:dead:beef::1"]
|
||||||
IP4_RANGES = ['172.16.0.0/24', '192.168.0.0/24']
|
IP4_RANGES = ["172.16.0.0/24", "192.168.0.0/24"]
|
||||||
IP6_RANGES = ['2001:dead:beef::/64', '2001:dada:b001::/64']
|
IP6_RANGES = ["2001:dead:beef::/64", "2001:dada:b001::/64"]
|
||||||
|
|
||||||
|
|
||||||
class TestIPExtension(unittest.TestCase):
|
class TestIPExtension(unittest.TestCase):
|
||||||
def setUp(self):
|
def setUp(self):
|
||||||
if not (test_root / '_static').exists():
|
if not (test_root / "_static").exists():
|
||||||
(test_root / '_static').mkdir()
|
(test_root / "_static").mkdir()
|
||||||
self.feed_warnfile = StringIO()
|
self.feed_warnfile = StringIO()
|
||||||
self.app = TestApp(
|
self.app = SphinxTestApplication(
|
||||||
buildername='html', warning=self.feed_warnfile, cleanenv=True)
|
buildername="html", warning=self.feed_warnfile, cleanenv=True
|
||||||
|
)
|
||||||
self.app.build(force_all=True, filenames=[])
|
self.app.build(force_all=True, filenames=[])
|
||||||
|
|
||||||
def tearDown(self):
|
def tearDown(self):
|
||||||
self.app.cleanup()
|
self.app.cleanup()
|
||||||
(test_root / '_build').rmtree(True)
|
shutil.rmtree((test_root / "_build"))
|
||||||
|
|
||||||
def test_ip_domaindata(self):
|
def test_ip_domaindata(self):
|
||||||
self.assertIn('ip', self.app.env.domaindata)
|
self.assertIn("ip", self.app.env.domaindata)
|
||||||
ipdomdata = self.app.env.domaindata['ip']
|
ipdomdata = self.app.env.domaindata["ip"]
|
||||||
self.assertIn('v4', ipdomdata)
|
self.assertIn("ip_refs", ipdomdata)
|
||||||
self.assertIn('v6', ipdomdata)
|
self.assertIn("range_refs", ipdomdata)
|
||||||
self.assertIn('v4range', ipdomdata)
|
self.assertIn("range_nodes", ipdomdata)
|
||||||
self.assertIn('v6range', ipdomdata)
|
self.assertIn("ranges", ipdomdata)
|
||||||
self.assertIn('ips', ipdomdata)
|
self.assertIn("ip_dict", ipdomdata)
|
||||||
|
|
||||||
def find_in_index(self, entry):
|
def find_in_index(self, entry):
|
||||||
indexentries = self.app.env.indexentries
|
indexentries = self.app.env.get_domain("index").entries
|
||||||
for index in indexentries:
|
for index in indexentries:
|
||||||
for value in indexentries[index]:
|
for value in indexentries[index]:
|
||||||
if value[1] == entry:
|
if value[1] == entry:
|
||||||
|
@ -42,19 +43,15 @@ class TestIPExtension(unittest.TestCase):
|
||||||
self.fail("%s not found in index" % entry)
|
self.fail("%s not found in index" % entry)
|
||||||
|
|
||||||
def test_ip4_addresses(self):
|
def test_ip4_addresses(self):
|
||||||
ipv4 = self.app.env.domaindata['ip']['v4']
|
ips = self.app.env.domaindata["ip"]["ip_refs"]
|
||||||
ips = self.app.env.domaindata['ip']['ips']
|
|
||||||
for ip in IP4_ADDRESSES:
|
for ip in IP4_ADDRESSES:
|
||||||
self.assertIn(ip, ipv4)
|
self.assertIn(ip, ips)
|
||||||
self.assertIn(ip, [item['ip'] for item in ips])
|
|
||||||
self.find_in_index("IPv4 address; %s" % ip)
|
self.find_in_index("IPv4 address; %s" % ip)
|
||||||
self.find_in_index("%s; Test page 2" % ip)
|
self.find_in_index("%s; Test page 2" % ip)
|
||||||
|
|
||||||
def test_ip6_addresses(self):
|
def test_ip6_addresses(self):
|
||||||
ipv6 = self.app.env.domaindata['ip']['v6']
|
ips = self.app.env.domaindata["ip"]["ip_refs"]
|
||||||
ips = self.app.env.domaindata['ip']['ips']
|
|
||||||
for ip in IP6_ADDRESSES:
|
for ip in IP6_ADDRESSES:
|
||||||
self.assertIn(ip, ipv6)
|
self.assertIn(ip, ips)
|
||||||
self.assertIn(ip, [item['ip'] for item in ips])
|
|
||||||
self.find_in_index("IPv6 address; %s" % ip)
|
self.find_in_index("IPv6 address; %s" % ip)
|
||||||
self.find_in_index("%s; Test page 2" % ip)
|
self.find_in_index("%s; Test page 2" % ip)
|
||||||
|
|
120
tests/util.py
120
tests/util.py
|
@ -12,20 +12,26 @@ import shutil
|
||||||
import sys
|
import sys
|
||||||
import tempfile
|
import tempfile
|
||||||
from functools import wraps
|
from functools import wraps
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
from path import Path
|
|
||||||
from sphinx import application
|
from sphinx import application
|
||||||
|
|
||||||
__all__ = [
|
__all__ = [
|
||||||
'test_root',
|
"test_root",
|
||||||
'raises', 'raises_msg', 'Struct',
|
"raises",
|
||||||
'ListOutput', 'TestApp', 'with_app', 'gen_with_app',
|
"raises_msg",
|
||||||
'Path', 'with_tempdir', 'write_file',
|
"Struct",
|
||||||
'sprint',
|
"ListOutput",
|
||||||
|
"SphinxTestApplication",
|
||||||
|
"with_app",
|
||||||
|
"gen_with_app",
|
||||||
|
"with_tempdir",
|
||||||
|
"write_file",
|
||||||
|
"sprint",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
|
||||||
test_root = Path(__file__).parent.joinpath('root').abspath()
|
test_root = Path(__file__).parent.joinpath("root").absolute()
|
||||||
|
|
||||||
|
|
||||||
def _excstr(exc):
|
def _excstr(exc):
|
||||||
|
@ -44,8 +50,7 @@ def raises(exc, func, *args, **kwds):
|
||||||
except exc:
|
except exc:
|
||||||
pass
|
pass
|
||||||
else:
|
else:
|
||||||
raise AssertionError('%s did not raise %s' %
|
raise AssertionError("%s did not raise %s" % (func.__name__, _excstr(exc)))
|
||||||
(func.__name__, _excstr(exc)))
|
|
||||||
|
|
||||||
|
|
||||||
def raises_msg(exc, msg, func, *args, **kwds):
|
def raises_msg(exc, msg, func, *args, **kwds):
|
||||||
|
@ -56,10 +61,9 @@ def raises_msg(exc, msg, func, *args, **kwds):
|
||||||
try:
|
try:
|
||||||
func(*args, **kwds)
|
func(*args, **kwds)
|
||||||
except exc as err:
|
except exc as err:
|
||||||
assert msg in str(err), "\"%s\" not in \"%s\"" % (msg, err)
|
assert msg in str(err), '"%s" not in "%s"' % (msg, err)
|
||||||
else:
|
else:
|
||||||
raise AssertionError('%s did not raise %s' %
|
raise AssertionError("%s did not raise %s" % (func.__name__, _excstr(exc)))
|
||||||
(func.__name__, _excstr(exc)))
|
|
||||||
|
|
||||||
|
|
||||||
class Struct(object):
|
class Struct(object):
|
||||||
|
@ -71,6 +75,7 @@ class ListOutput(object):
|
||||||
"""
|
"""
|
||||||
File-like object that collects written text in a list.
|
File-like object that collects written text in a list.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def __init__(self, name):
|
def __init__(self, name):
|
||||||
self.name = name
|
self.name = name
|
||||||
self.content = []
|
self.content = []
|
||||||
|
@ -82,42 +87,53 @@ class ListOutput(object):
|
||||||
self.content.append(text)
|
self.content.append(text)
|
||||||
|
|
||||||
|
|
||||||
class TestApp(application.Sphinx):
|
class SphinxTestApplication(application.Sphinx):
|
||||||
"""
|
"""
|
||||||
A subclass of :class:`Sphinx` that runs on the test root, with some
|
A subclass of :class:`Sphinx` that runs on the test root, with some
|
||||||
better default values for the initialization parameters.
|
better default values for the initialization parameters.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def __init__(self, srcdir=None, confdir=None, outdir=None, doctreedir=None,
|
def __init__(
|
||||||
buildername='html', confoverrides=None,
|
self,
|
||||||
status=None, warning=None, freshenv=None,
|
src_dir=None,
|
||||||
warningiserror=None, tags=None,
|
confdir=None,
|
||||||
confname='conf.py', cleanenv=False):
|
out_dir=None,
|
||||||
|
doctreedir=None,
|
||||||
|
buildername="html",
|
||||||
|
confoverrides=None,
|
||||||
|
status=None,
|
||||||
|
warning=None,
|
||||||
|
freshenv=None,
|
||||||
|
warningiserror=None,
|
||||||
|
tags=None,
|
||||||
|
confname="conf.py",
|
||||||
|
cleanenv=False,
|
||||||
|
):
|
||||||
|
|
||||||
application.CONFIG_FILENAME = confname
|
application.CONFIG_FILENAME = confname
|
||||||
|
|
||||||
self.cleanup_trees = [test_root / 'generated']
|
self.cleanup_trees = [test_root / "generated"]
|
||||||
|
|
||||||
if srcdir is None:
|
if src_dir is None:
|
||||||
srcdir = test_root
|
src_dir = test_root
|
||||||
if srcdir == '(temp)':
|
if src_dir == "(temp)":
|
||||||
tempdir = Path(tempfile.mkdtemp())
|
tempdir = Path(tempfile.mkdtemp())
|
||||||
self.cleanup_trees.append(tempdir)
|
self.cleanup_trees.append(tempdir)
|
||||||
temproot = tempdir / 'root'
|
temp_root = tempdir / "root"
|
||||||
test_root.copytree(temproot)
|
shutil.copytree(test_root.resolve(), temp_root.resolve())
|
||||||
srcdir = temproot
|
src_dir = temp_root
|
||||||
else:
|
else:
|
||||||
srcdir = Path(srcdir)
|
src_dir = Path(src_dir)
|
||||||
self.builddir = srcdir.joinpath('_build')
|
self.builddir = src_dir.joinpath("_build")
|
||||||
if confdir is None:
|
if confdir is None:
|
||||||
confdir = srcdir
|
confdir = src_dir
|
||||||
if outdir is None:
|
if out_dir is None:
|
||||||
outdir = srcdir.joinpath(self.builddir, buildername)
|
out_dir = src_dir.joinpath(self.builddir, buildername)
|
||||||
if not outdir.isdir():
|
if not out_dir.is_dir():
|
||||||
outdir.makedirs()
|
out_dir.mkdir(parents=True)
|
||||||
self.cleanup_trees.insert(0, outdir)
|
self.cleanup_trees.insert(0, out_dir)
|
||||||
if doctreedir is None:
|
if doctreedir is None:
|
||||||
doctreedir = srcdir.joinpath(srcdir, self.builddir, 'doctrees')
|
doctreedir = src_dir.joinpath(src_dir, self.builddir, "doctrees")
|
||||||
if cleanenv:
|
if cleanenv:
|
||||||
self.cleanup_trees.insert(0, doctreedir)
|
self.cleanup_trees.insert(0, doctreedir)
|
||||||
if confoverrides is None:
|
if confoverrides is None:
|
||||||
|
@ -125,15 +141,26 @@ class TestApp(application.Sphinx):
|
||||||
if status is None:
|
if status is None:
|
||||||
status = io.StringIO()
|
status = io.StringIO()
|
||||||
if warning is None:
|
if warning is None:
|
||||||
warning = ListOutput('stderr')
|
warning = ListOutput("stderr")
|
||||||
if freshenv is None:
|
if freshenv is None:
|
||||||
freshenv = False
|
freshenv = False
|
||||||
if warningiserror is None:
|
if warningiserror is None:
|
||||||
warningiserror = False
|
warningiserror = False
|
||||||
|
|
||||||
application.Sphinx.__init__(self, srcdir, confdir, outdir, doctreedir,
|
application.Sphinx.__init__(
|
||||||
buildername, confoverrides, status, warning,
|
self,
|
||||||
freshenv, warningiserror, tags)
|
str(src_dir),
|
||||||
|
confdir,
|
||||||
|
out_dir,
|
||||||
|
doctreedir,
|
||||||
|
buildername,
|
||||||
|
confoverrides,
|
||||||
|
status,
|
||||||
|
warning,
|
||||||
|
freshenv,
|
||||||
|
warningiserror,
|
||||||
|
tags,
|
||||||
|
)
|
||||||
|
|
||||||
def cleanup(self, doctrees=False):
|
def cleanup(self, doctrees=False):
|
||||||
for tree in self.cleanup_trees:
|
for tree in self.cleanup_trees:
|
||||||
|
@ -145,14 +172,17 @@ def with_app(*args, **kwargs):
|
||||||
Make a TestApp with args and kwargs, pass it to the test and clean up
|
Make a TestApp with args and kwargs, pass it to the test and clean up
|
||||||
properly.
|
properly.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def generator(func):
|
def generator(func):
|
||||||
@wraps(func)
|
@wraps(func)
|
||||||
def deco(*args2, **kwargs2):
|
def deco(*args2, **kwargs2):
|
||||||
app = TestApp(*args, **kwargs)
|
app = SphinxTestApplication(*args, **kwargs)
|
||||||
func(app, *args2, **kwargs2)
|
func(app, *args2, **kwargs2)
|
||||||
# don't execute cleanup if test failed
|
# don't execute cleanup if test failed
|
||||||
app.cleanup()
|
app.cleanup()
|
||||||
|
|
||||||
return deco
|
return deco
|
||||||
|
|
||||||
return generator
|
return generator
|
||||||
|
|
||||||
|
|
||||||
|
@ -161,15 +191,18 @@ def gen_with_app(*args, **kwargs):
|
||||||
Make a TestApp with args and kwargs, pass it to the test and clean up
|
Make a TestApp with args and kwargs, pass it to the test and clean up
|
||||||
properly.
|
properly.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def generator(func):
|
def generator(func):
|
||||||
@wraps(func)
|
@wraps(func)
|
||||||
def deco(*args2, **kwargs2):
|
def deco(*args2, **kwargs2):
|
||||||
app = TestApp(*args, **kwargs)
|
app = SphinxTestApplication(*args, **kwargs)
|
||||||
for item in func(app, *args2, **kwargs2):
|
for item in func(app, *args2, **kwargs2):
|
||||||
yield item
|
yield item
|
||||||
# don't execute cleanup if test failed
|
# don't execute cleanup if test failed
|
||||||
app.cleanup()
|
app.cleanup()
|
||||||
|
|
||||||
return deco
|
return deco
|
||||||
|
|
||||||
return generator
|
return generator
|
||||||
|
|
||||||
|
|
||||||
|
@ -177,16 +210,17 @@ def with_tempdir(func):
|
||||||
def new_func():
|
def new_func():
|
||||||
tempdir = Path(tempfile.mkdtemp())
|
tempdir = Path(tempfile.mkdtemp())
|
||||||
func(tempdir)
|
func(tempdir)
|
||||||
tempdir.rmtree()
|
tempdir.rmdir()
|
||||||
|
|
||||||
new_func.__name__ = func.__name__
|
new_func.__name__ = func.__name__
|
||||||
return new_func
|
return new_func
|
||||||
|
|
||||||
|
|
||||||
def write_file(name, contents):
|
def write_file(name, contents):
|
||||||
f = open(str(name), 'wb')
|
f = open(str(name), "wb")
|
||||||
f.write(contents)
|
f.write(contents)
|
||||||
f.close()
|
f.close()
|
||||||
|
|
||||||
|
|
||||||
def sprint(*args):
|
def sprint(*args):
|
||||||
sys.stderr.write(' '.join(map(str, args)) + '\n')
|
sys.stderr.write(" ".join(map(str, args)) + "\n")
|
||||||
|
|
26
tox.ini
Normal file
26
tox.ini
Normal file
|
@ -0,0 +1,26 @@
|
||||||
|
[tox]
|
||||||
|
requires =
|
||||||
|
tox>=4
|
||||||
|
env_list = lint, type, py{39,310,311,312}
|
||||||
|
|
||||||
|
[testenv]
|
||||||
|
description = run unit tests
|
||||||
|
deps =
|
||||||
|
pytest>=7
|
||||||
|
pytest-sugar
|
||||||
|
commands =
|
||||||
|
pytest {posargs:tests}
|
||||||
|
|
||||||
|
[testenv:lint]
|
||||||
|
description = run linters
|
||||||
|
skip_install = true
|
||||||
|
deps =
|
||||||
|
black==22.12
|
||||||
|
commands = black {posargs:.}
|
||||||
|
|
||||||
|
[testenv:type]
|
||||||
|
description = run type checks
|
||||||
|
deps =
|
||||||
|
mypy>=0.991
|
||||||
|
commands =
|
||||||
|
mypy {posargs:--install-types --non-interactive jandd tests}
|
Loading…
Reference in a new issue