Skip to content
Snippets Groups Projects
Commit f1990355 authored by Piotr Ożarowski's avatar Piotr Ożarowski
Browse files

New upstream version 0.4.1

parent b588b3d9
No related branches found
Tags upstream/0.4.1
No related merge requests found
Metadata-Version: 1.1
Name: sphinx-paramlinks
Version: 0.3.7
Version: 0.4.1
Summary: Allows param links in Sphinx function/method descriptions to be linkable
Home-page: http://github.com/sqlalchemyorg/sphinx-paramlinks
Author: Mike Bayer
......
Metadata-Version: 1.1
Name: sphinx-paramlinks
Version: 0.3.7
Version: 0.4.1
Summary: Allows param links in Sphinx function/method descriptions to be linkable
Home-page: http://github.com/sqlalchemyorg/sphinx-paramlinks
Author: Mike Bayer
......
__version__ = '0.3.7'
__version__ = '0.4.1'
from .sphinx_paramlinks import setup # noqa
......@@ -9,25 +9,36 @@ from sphinx.domains.python import PyXRefRole
from sphinx.domains.python import PythonDomain
from distutils.version import LooseVersion
from sphinx import __version__
# the searchindex.js system relies upon the object types
# in the PythonDomain to create search entries
from sphinx.domains import ObjType
from sphinx.util import logging
PythonDomain.object_types['parameter'] = ObjType('parameter', 'param')
PythonDomain.object_types["parameter"] = ObjType("parameter", "param")
LOG = logging.getLogger(__name__)
def _is_html(app):
return app.builder.name in ('html', 'readthedocs')
return app.builder.name in ("html", "readthedocs")
# https://www.sphinx-doc.org/en/master/extdev/deprecated.html
def _indexentries(env):
return env.domains["index"].entries
# pre 3.0:
# return env.indexentries
def _tempdata(app):
if '_sphinx_paramlinks_index' in app.env.indexentries:
idx = app.env.indexentries['_sphinx_paramlinks_index']
if "_sphinx_paramlinks_index" in _indexentries(app.env):
idx = _indexentries(app.env)["_sphinx_paramlinks_index"]
else:
app.env.indexentries['_sphinx_paramlinks_index'] = idx = {}
_indexentries(app.env)["_sphinx_paramlinks_index"] = idx = {}
return idx
......@@ -38,7 +49,9 @@ def autodoc_process_docstring(app, what, name, obj, options, lines):
idx = _tempdata(app)
docname = app.env.temp_data['docname']
docname = app.env.temp_data.get("docname")
if not docname:
return
if docname in idx:
doc_idx = idx[docname]
else:
......@@ -51,39 +64,49 @@ def autodoc_process_docstring(app, what, name, obj, options, lines):
name = name[0:-9]
def cvt(m):
modifier, objname, paramname = m.group(1) or '', name, m.group(2)
modifier, objname, paramname = m.group(1) or "", name, m.group(2)
refname = _refname_from_paramname(paramname, strip_markup=True)
item = ('single', '%s (%s parameter)' % (refname, objname),
'%s.params.%s' % (objname, refname), '')
if LooseVersion(__version__) >= LooseVersion('1.4.0'):
item = (
"single",
"%s (%s parameter)" % (refname, objname),
"%s.params.%s" % (objname, refname),
"",
)
if LooseVersion(__version__) >= LooseVersion("1.4.0"):
item += (None,)
doc_idx.append(item)
return ":param %s_sphinx_paramlinks_%s.%s:" % (
modifier, objname, paramname)
modifier,
objname,
paramname,
)
def secondary_cvt(m):
modifier, objname, paramname = m.group(1) or '', name, m.group(2)
modifier, objname, paramname = m.group(1) or "", name, m.group(2)
return ":type %s_sphinx_paramlinks_%s.%s:" % (
modifier, objname, paramname)
line = re.sub(r'^:param ([^:]+? )?([^:]+?):', cvt, line)
line = re.sub(r'^:type ([^:]+? )?([^:]+?):', secondary_cvt, line)
modifier,
objname,
paramname,
)
line = re.sub(r"^:param ([^:]+? )?([^:]+?):", cvt, line)
line = re.sub(r"^:type ([^:]+? )?([^:]+?):", secondary_cvt, line)
return line
if what in ('function', 'method', 'class'):
if what in ("function", "method", "class"):
lines[:] = [_cvt_param(name, line) for line in lines]
def _refname_from_paramname(paramname, strip_markup=False):
literal_match = re.match(r'^``(.+?)``$', paramname)
literal_match = re.match(r"^``(.+?)``$", paramname)
if literal_match:
paramname = literal_match.group(1)
refname = paramname
eq_match = re.match(r'(.+?)=.+$', refname)
eq_match = re.match(r"(.+?)=.+$", refname)
if eq_match:
refname = eq_match.group(1)
if strip_markup:
refname = re.sub(r'\\', '', refname)
refname = re.sub(r"\\", "", refname)
return refname
......@@ -101,15 +124,12 @@ class LinkParams(Transform):
for ref in self.document.traverse(nodes.strong):
text = ref.astext()
if text.startswith("_sphinx_paramlinks_"):
components = re.match(r'_sphinx_paramlinks_(.+)\.(.+)$', text)
components = re.match(r"_sphinx_paramlinks_(.+)\.(.+)$", text)
location, paramname = components.group(1, 2)
refname = _refname_from_paramname(paramname)
refid = "%s.params.%s" % (location, refname)
ref.parent.insert(
0,
nodes.target('', '', ids=[refid])
)
ref.parent.insert(0, nodes.target("", "", ids=[refid]))
del ref[0]
ref.insert(0, nodes.Text(paramname, paramname))
......@@ -136,8 +156,10 @@ class LinkParams(Transform):
# readthedocs proving..it's not.
# TODO: need to take into account a type name
# with the parens.
if isinstance(node, nodes.TextElement) and \
node.astext() == paramname:
if (
isinstance(node, nodes.TextElement)
and node.astext() == paramname
):
break
else:
return
......@@ -145,14 +167,15 @@ class LinkParams(Transform):
ref.parent.insert(
pos + 1,
nodes.reference(
'', '',
"",
"",
nodes.Text(u"", u""),
refid=refid,
# paramlink is our own CSS class, headerlink
# is theirs. Trying to get everything we can for
# existing symbols...
classes=['paramlink', 'headerlink']
)
classes=["paramlink", "headerlink"],
),
)
......@@ -163,10 +186,10 @@ def lookup_params(app, env, node, contnode):
# the Sphinx BuildEnvironment then gives us one more chance to do a lookup
# here.
if node['reftype'] != 'paramref':
if node["reftype"] != "paramref":
return None
target = node['reftarget']
target = node["reftarget"]
tokens = target.split(".")
resolve_target = ".".join(tokens[0:-1])
......@@ -175,13 +198,13 @@ def lookup_params(app, env, node, contnode):
# emulate the approach within
# sphinx.environment.BuildEnvironment.resolve_references
try:
domain = env.domains[node['refdomain']] # hint: this will be 'py'
domain = env.domains[node["refdomain"]] # hint: this will be 'py'
except KeyError:
return None
# BuildEnvironment doesn't pass us "fromdocname" here as the
# fallback, oh well
refdoc = node.get('refdoc', None)
refdoc = node.get("refdoc", None)
# we call the same "resolve_xref" that BuildEnvironment just tried
# to call for us, but we load the call with information we know
......@@ -191,32 +214,35 @@ def lookup_params(app, env, node, contnode):
for search in ["meth", "class", "func"]:
newnode = domain.resolve_xref(
env, refdoc, app.builder,
search, resolve_target, node, contnode)
env, refdoc, app.builder, search, resolve_target, node, contnode
)
if newnode is not None:
break
if newnode is not None:
# assuming we found it, tack the paramname back onto to the final
# URI.
if 'refuri' in newnode:
newnode['refuri'] += ".params." + paramname
elif 'refid' in newnode:
newnode['refid'] += ".params." + paramname
if "refuri" in newnode:
newnode["refuri"] += ".params." + paramname
elif "refid" in newnode:
newnode["refid"] += ".params." + paramname
return newnode
def add_stylesheet(app):
app.add_stylesheet('sphinx_paramlinks.css')
# changed in 1.8 from add_stylesheet()
# https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file
app.add_css_file("sphinx_paramlinks.css")
def copy_stylesheet(app, exception):
LOG.info(
bold('The name of the builder is: %s' % app.builder.name), nonl=True)
bold("The name of the builder is: %s" % app.builder.name), nonl=True
)
if not _is_html(app) or exception:
return
LOG.info(bold('Copying sphinx_paramlinks stylesheet... '), nonl=True)
LOG.info(bold("Copying sphinx_paramlinks stylesheet... "), nonl=True)
source = os.path.abspath(os.path.dirname(__file__))
......@@ -224,9 +250,9 @@ def copy_stylesheet(app, exception):
# sphinx.builders.html.StandaloneHTMLBuilder.copy_static_files.
# would be nice if Sphinx could improve the API here so that we just
# give it the path to a .css file and it does the right thing.
dest = os.path.join(app.builder.outdir, '_static', 'sphinx_paramlinks.css')
dest = os.path.join(app.builder.outdir, "_static", "sphinx_paramlinks.css")
copyfile(os.path.join(source, "sphinx_paramlinks.css"), dest)
LOG.info('done')
LOG.info("done")
def build_index(app, doctree):
......@@ -234,13 +260,25 @@ def build_index(app, doctree):
for docname in entries:
doc_entries = entries[docname]
app.env.indexentries[docname].extend(doc_entries)
for entry in doc_entries:
sing, desc, ref, extra = entry[:4]
app.env.domains['py'].data['objects'][ref] = (docname, 'parameter')
_indexentries(app.env)[docname].extend(doc_entries)
if LooseVersion(__version__) >= LooseVersion("3.0.0"):
for entry in doc_entries:
sing, desc, ref, extra = entry[:4]
app.env.domains["py"].data["objects"][ref] = (
docname,
ref,
"parameter",
)
else:
for entry in doc_entries:
sing, desc, ref, extra = entry[:4]
app.env.domains["py"].data["objects"][ref] = (
docname,
"parameter",
)
app.env.indexentries.pop('_sphinx_paramlinks_index')
_indexentries(app.env).pop("_sphinx_paramlinks_index")
def setup(app):
......@@ -251,8 +289,13 @@ def setup(app):
# sphinx node along with contextual information.
app.add_role_to_domain("py", "paramref", PyXRefRole())
app.connect('autodoc-process-docstring', autodoc_process_docstring)
app.connect('builder-inited', add_stylesheet)
app.connect('build-finished', copy_stylesheet)
app.connect('missing-reference', lookup_params)
app.connect('doctree-read', build_index)
app.connect("autodoc-process-docstring", autodoc_process_docstring)
app.connect("builder-inited", add_stylesheet)
app.connect("build-finished", copy_stylesheet)
app.connect("missing-reference", lookup_params)
app.connect("doctree-read", build_index)
return {
"parallel_read_safe": True,
"parallel_write_safe": True,
}
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment