sphinx-paramlinks-0.3.2/0000775000175000017500000000000012714427644016265 5ustar classicclassic00000000000000sphinx-paramlinks-0.3.2/setup.py0000644000175000017500000000217512260332142017762 0ustar classicclassic00000000000000from setuptools import setup import os import re v = open(os.path.join(os.path.dirname(__file__), 'sphinx_paramlinks/__init__.py')) VERSION = re.compile(r".*__version__ = '(.*?)'", re.S).match(v.read()).group(1) v.close() readme = os.path.join(os.path.dirname(__file__), 'README.rst') setup(name='sphinx-paramlinks', version=VERSION, description="Allows param links in Sphinx function/method descriptions to be linkable", long_description=open(readme).read(), classifiers=[ 'Development Status :: 3 - Alpha', 'Environment :: Console', 'Intended Audience :: Developers', 'Programming Language :: Python', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: Implementation :: CPython', 'Programming Language :: Python :: Implementation :: PyPy', 'Topic :: Documentation', ], keywords='sphinx', author='Mike Bayer', author_email='mike@zzzcomputing.com', url='http://bitbucket.org/zzzeek/sphinx-paramlinks', license='MIT', packages=['sphinx_paramlinks'], include_package_data=True, zip_safe=False, ) sphinx-paramlinks-0.3.2/sphinx_paramlinks.egg-info/0000775000175000017500000000000012714427644023511 5ustar classicclassic00000000000000sphinx-paramlinks-0.3.2/sphinx_paramlinks.egg-info/SOURCES.txt0000644000175000017500000000054012714427644025372 0ustar classicclassic00000000000000LICENSE MANIFEST.in README.rst setup.py sphinx_paramlinks/__init__.py sphinx_paramlinks/sphinx_paramlinks.css sphinx_paramlinks/sphinx_paramlinks.py sphinx_paramlinks.egg-info/PKG-INFO sphinx_paramlinks.egg-info/SOURCES.txt sphinx_paramlinks.egg-info/dependency_links.txt sphinx_paramlinks.egg-info/not-zip-safe sphinx_paramlinks.egg-info/top_level.txtsphinx-paramlinks-0.3.2/sphinx_paramlinks.egg-info/PKG-INFO0000644000175000017500000001310312714427644024602 0ustar classicclassic00000000000000Metadata-Version: 1.1 Name: sphinx-paramlinks Version: 0.3.2 Summary: Allows param links in Sphinx function/method descriptions to be linkable Home-page: http://bitbucket.org/zzzeek/sphinx-paramlinks Author: Mike Bayer Author-email: mike@zzzcomputing.com License: MIT Description: ================== Sphinx Paramlinks ================== A `Sphinx `_ extension which allows ``:param:`` directives within Python documentation to be linkable. This is an experimental, possibly-not-useful extension that's used by the `SQLAlchemy `_ project and related projects. Configuration ============= Just turn it on in ``conf.py``:: extensions = [ 'sphinx_paramlinks', # your other sphinx extensions # ... ] Stylesheet ========== The paragraph link involves a short stylesheet, to allow the links to be visible when hovered. This sheet is called ``sphinx_paramlinks.css`` and the plugin will copy it to the ``_static`` directory of the output automatically. The stylesheet is added to the ``css_files`` list present in the template namespace for Sphinx via the ``Sphinx.add_stylesheet()`` hook. Features ======== * ``:param:`` directives within Sphinx function/method descriptions will be given a paragraph link so that they can be linked to externally. * A new text role ``:paramref:`` is added, which works like ``:meth:``, ``:func:``, etc. Just append the parameter name as an additional token:: :paramref:`.EnvironmentContext.configure.transactional_ddl` The directive makes use of the existing Python role to do the method/function lookup, using the ``:obj:`` role; then the parameter name is applied separately to produce the final reference link. * The paramlinks are also added to the master index as well as the list of domain objects, which allows them to be searchable through the searchindex.js system. (new in 0.3.0) Compatibility ============= Python Compatibility -------------------- The extension was developed on Python 2.7, but is compatible with at least Python 3.3 as well. It contains one ``u''`` literal - these are supported again as of Python 3.3. Sphinx Compatibility -------------------- I've tried *very* hard to make as few assumptions as possible about Sphinx and to use only very simple public APIs, so that architectural changes in future Sphinx versions won't break this plugin. To come up with this plugin I spent many hours with Sphinx source and tried many different approaches to various elements of functionality; hopefully what's here is as simple and stable as possible based on the current extension capabilities of Sphinx. One element that involves using a bit of internals is the usage of the ``sphinx.domains.python.PyXRefRole`` class, which is currently the Sphinx class that defines roles for things like ``:meth:``, ``:func:``, etc. The object is used as-is in order to define the ``:paramref:`` role; the product of this role is later transformed using standard hooks. Another assumption is that in order to locate the RST nodes Sphinx creates for the ``:param:`` tags, we look at ``nodes.strong``, assuming that this is the type of node currently used to render ``:param:`` within RST. If this changes, or needs to be expanded to support other domains, this traversal can be opened up as needed. This part was difficult as Sphinx really doesn't provide any hooks into how the "Info Field List" aspect of domains is handled. Overall, the approach here is to apply extra information to constructs going into the Sphinx system, then do some transformations as the data comes back out. This relies on as little of how Sphinx does its thing as possible, rather than going with custom domains and heavy use of injected APIs which may change in future releases. Future Enhancements / Missing Features ====================================== The extension currently does only ``:param:`` elements within the Python role, but could also be expanded to support other Python role elements such as ``:returns:``, ``:raises:``, etc., and perhaps also could be made to support similar features in other roles. Another area that's not addressed at all is search. While the params here are linked, these objects are currently not part of the search index Sphinx creates in any usable way. I don't know what would be involved to make that work. Keywords: sphinx Platform: UNKNOWN Classifier: Development Status :: 3 - Alpha Classifier: Environment :: Console Classifier: Intended Audience :: Developers Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Topic :: Documentation sphinx-paramlinks-0.3.2/sphinx_paramlinks.egg-info/dependency_links.txt0000644000175000017500000000000112714427644027555 0ustar classicclassic00000000000000 sphinx-paramlinks-0.3.2/sphinx_paramlinks.egg-info/top_level.txt0000644000175000017500000000002212714427644026233 0ustar classicclassic00000000000000sphinx_paramlinks sphinx-paramlinks-0.3.2/sphinx_paramlinks.egg-info/not-zip-safe0000644000175000017500000000000112260332165025722 0ustar classicclassic00000000000000 sphinx-paramlinks-0.3.2/README.rst0000644000175000017500000001010012643541712017734 0ustar classicclassic00000000000000================== Sphinx Paramlinks ================== A `Sphinx `_ extension which allows ``:param:`` directives within Python documentation to be linkable. This is an experimental, possibly-not-useful extension that's used by the `SQLAlchemy `_ project and related projects. Configuration ============= Just turn it on in ``conf.py``:: extensions = [ 'sphinx_paramlinks', # your other sphinx extensions # ... ] Stylesheet ========== The paragraph link involves a short stylesheet, to allow the links to be visible when hovered. This sheet is called ``sphinx_paramlinks.css`` and the plugin will copy it to the ``_static`` directory of the output automatically. The stylesheet is added to the ``css_files`` list present in the template namespace for Sphinx via the ``Sphinx.add_stylesheet()`` hook. Features ======== * ``:param:`` directives within Sphinx function/method descriptions will be given a paragraph link so that they can be linked to externally. * A new text role ``:paramref:`` is added, which works like ``:meth:``, ``:func:``, etc. Just append the parameter name as an additional token:: :paramref:`.EnvironmentContext.configure.transactional_ddl` The directive makes use of the existing Python role to do the method/function lookup, using the ``:obj:`` role; then the parameter name is applied separately to produce the final reference link. * The paramlinks are also added to the master index as well as the list of domain objects, which allows them to be searchable through the searchindex.js system. (new in 0.3.0) Compatibility ============= Python Compatibility -------------------- The extension was developed on Python 2.7, but is compatible with at least Python 3.3 as well. It contains one ``u''`` literal - these are supported again as of Python 3.3. Sphinx Compatibility -------------------- I've tried *very* hard to make as few assumptions as possible about Sphinx and to use only very simple public APIs, so that architectural changes in future Sphinx versions won't break this plugin. To come up with this plugin I spent many hours with Sphinx source and tried many different approaches to various elements of functionality; hopefully what's here is as simple and stable as possible based on the current extension capabilities of Sphinx. One element that involves using a bit of internals is the usage of the ``sphinx.domains.python.PyXRefRole`` class, which is currently the Sphinx class that defines roles for things like ``:meth:``, ``:func:``, etc. The object is used as-is in order to define the ``:paramref:`` role; the product of this role is later transformed using standard hooks. Another assumption is that in order to locate the RST nodes Sphinx creates for the ``:param:`` tags, we look at ``nodes.strong``, assuming that this is the type of node currently used to render ``:param:`` within RST. If this changes, or needs to be expanded to support other domains, this traversal can be opened up as needed. This part was difficult as Sphinx really doesn't provide any hooks into how the "Info Field List" aspect of domains is handled. Overall, the approach here is to apply extra information to constructs going into the Sphinx system, then do some transformations as the data comes back out. This relies on as little of how Sphinx does its thing as possible, rather than going with custom domains and heavy use of injected APIs which may change in future releases. Future Enhancements / Missing Features ====================================== The extension currently does only ``:param:`` elements within the Python role, but could also be expanded to support other Python role elements such as ``:returns:``, ``:raises:``, etc., and perhaps also could be made to support similar features in other roles. Another area that's not addressed at all is search. While the params here are linked, these objects are currently not part of the search index Sphinx creates in any usable way. I don't know what would be involved to make that work.sphinx-paramlinks-0.3.2/MANIFEST.in0000644000175000017500000000011312260325366020006 0ustar classicclassic00000000000000recursive-include sphinx_paramlinks *.py *.css include README* LICENSE sphinx-paramlinks-0.3.2/PKG-INFO0000664000175000017500000001310312714427644017360 0ustar classicclassic00000000000000Metadata-Version: 1.1 Name: sphinx-paramlinks Version: 0.3.2 Summary: Allows param links in Sphinx function/method descriptions to be linkable Home-page: http://bitbucket.org/zzzeek/sphinx-paramlinks Author: Mike Bayer Author-email: mike@zzzcomputing.com License: MIT Description: ================== Sphinx Paramlinks ================== A `Sphinx `_ extension which allows ``:param:`` directives within Python documentation to be linkable. This is an experimental, possibly-not-useful extension that's used by the `SQLAlchemy `_ project and related projects. Configuration ============= Just turn it on in ``conf.py``:: extensions = [ 'sphinx_paramlinks', # your other sphinx extensions # ... ] Stylesheet ========== The paragraph link involves a short stylesheet, to allow the links to be visible when hovered. This sheet is called ``sphinx_paramlinks.css`` and the plugin will copy it to the ``_static`` directory of the output automatically. The stylesheet is added to the ``css_files`` list present in the template namespace for Sphinx via the ``Sphinx.add_stylesheet()`` hook. Features ======== * ``:param:`` directives within Sphinx function/method descriptions will be given a paragraph link so that they can be linked to externally. * A new text role ``:paramref:`` is added, which works like ``:meth:``, ``:func:``, etc. Just append the parameter name as an additional token:: :paramref:`.EnvironmentContext.configure.transactional_ddl` The directive makes use of the existing Python role to do the method/function lookup, using the ``:obj:`` role; then the parameter name is applied separately to produce the final reference link. * The paramlinks are also added to the master index as well as the list of domain objects, which allows them to be searchable through the searchindex.js system. (new in 0.3.0) Compatibility ============= Python Compatibility -------------------- The extension was developed on Python 2.7, but is compatible with at least Python 3.3 as well. It contains one ``u''`` literal - these are supported again as of Python 3.3. Sphinx Compatibility -------------------- I've tried *very* hard to make as few assumptions as possible about Sphinx and to use only very simple public APIs, so that architectural changes in future Sphinx versions won't break this plugin. To come up with this plugin I spent many hours with Sphinx source and tried many different approaches to various elements of functionality; hopefully what's here is as simple and stable as possible based on the current extension capabilities of Sphinx. One element that involves using a bit of internals is the usage of the ``sphinx.domains.python.PyXRefRole`` class, which is currently the Sphinx class that defines roles for things like ``:meth:``, ``:func:``, etc. The object is used as-is in order to define the ``:paramref:`` role; the product of this role is later transformed using standard hooks. Another assumption is that in order to locate the RST nodes Sphinx creates for the ``:param:`` tags, we look at ``nodes.strong``, assuming that this is the type of node currently used to render ``:param:`` within RST. If this changes, or needs to be expanded to support other domains, this traversal can be opened up as needed. This part was difficult as Sphinx really doesn't provide any hooks into how the "Info Field List" aspect of domains is handled. Overall, the approach here is to apply extra information to constructs going into the Sphinx system, then do some transformations as the data comes back out. This relies on as little of how Sphinx does its thing as possible, rather than going with custom domains and heavy use of injected APIs which may change in future releases. Future Enhancements / Missing Features ====================================== The extension currently does only ``:param:`` elements within the Python role, but could also be expanded to support other Python role elements such as ``:returns:``, ``:raises:``, etc., and perhaps also could be made to support similar features in other roles. Another area that's not addressed at all is search. While the params here are linked, these objects are currently not part of the search index Sphinx creates in any usable way. I don't know what would be involved to make that work. Keywords: sphinx Platform: UNKNOWN Classifier: Development Status :: 3 - Alpha Classifier: Environment :: Console Classifier: Intended Audience :: Developers Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Topic :: Documentation sphinx-paramlinks-0.3.2/sphinx_paramlinks/0000775000175000017500000000000012714427644022017 5ustar classicclassic00000000000000sphinx-paramlinks-0.3.2/sphinx_paramlinks/sphinx_paramlinks.css0000644000175000017500000000013112260323724026242 0ustar classicclassic00000000000000a.paramlink { visibility: hidden; } li:hover > a.paramlink { visibility: visible; } sphinx-paramlinks-0.3.2/sphinx_paramlinks/sphinx_paramlinks.py0000664000175000017500000002165712714427501026126 0ustar classicclassic00000000000000#!coding: utf-8 import re from docutils import nodes from docutils.transforms import Transform import os from sphinx.util.osutil import copyfile from sphinx.util.console import bold 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 PythonDomain.object_types['parameter'] = ObjType('parameter', 'param') def _is_html(app): return app.builder.name in ('html', 'readthedocs') def _tempdata(app): if '_sphinx_paramlinks_index' in app.env.indexentries: idx = app.env.indexentries['_sphinx_paramlinks_index'] else: app.env.indexentries['_sphinx_paramlinks_index'] = idx = {} return idx def autodoc_process_docstring(app, what, name, obj, options, lines): # locate :param: lines within docstrings. augment the parameter # name with that of the parent object name plus a token we can # spot later. Also put an index entry in a temporary collection. idx = _tempdata(app) docname = app.env.temp_data['docname'] if docname in idx: doc_idx = idx[docname] else: idx[docname] = doc_idx = [] def _cvt_param(name, line): if name.endswith(".__init__"): # kill off __init__ if present, the links are always # off the class name = name[0:-9] def cvt(m): 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 += (None,) doc_idx.append(item) return ":param %s_sphinx_paramlinks_%s.%s:" % ( modifier, objname, paramname) return re.sub(r'^:param ([^:]+? )?([^:]+?):', cvt, line) 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) if literal_match: paramname = literal_match.group(1) refname = paramname eq_match = re.match(r'(.+?)=.+$', refname) if eq_match: refname = eq_match.group(1) if strip_markup: refname = re.sub(r'\\', '', refname) return refname class LinkParams(Transform): # apply references targets and optional references # to nodes that contain our target text. default_priority = 210 def apply(self): is_html = _is_html(self.document.settings.env.app) # seach nodes, which will include the titles for # those :param: directives, looking for our special token. # then fix up the text within the node. for ref in self.document.traverse(nodes.strong): text = ref.astext() if text.startswith("_sphinx_paramlinks_"): 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]) ) del ref[0] ref.insert(0, nodes.Text(paramname, paramname)) if is_html: # add the "p" thing only if we're the HTML builder. # using a real ¶, surprising, right? # http://docutils.sourceforge.net/FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document # "For example, say you want an em-dash (XML # character entity —, Unicode character # U+2014) in your document: use a real em-dash. # Insert concrete characters (e.g. type a real em- # dash) into your input file, using whatever # encoding suits your application, and tell # Docutils the input encoding. Docutils uses # Unicode internally, so the em-dash character is # a real em-dash internally." OK ! for pos, node in enumerate(ref.parent.children): # try to figure out where the node with the # paramname is. thought this was simple, but # 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: break else: return 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'] ) ) def lookup_params(app, env, node, contnode): # here, we catch the "pending xref" nodes that we created with # the "paramref" role we added. The resolve_xref() routine # knows nothing about this node type so it never finds anything; # the Sphinx BuildEnvironment then gives us one more chance to do a lookup # here. if node['reftype'] != 'paramref': return None target = node['reftarget'] tokens = target.split(".") resolve_target = ".".join(tokens[0:-1]) paramname = tokens[-1] # emulate the approach within # sphinx.environment.BuildEnvironment.resolve_references try: 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) # we call the same "resolve_xref" that BuildEnvironment just tried # to call for us, but we load the call with information we know # it can find, e.g. the "object" role (or we could use :meth:/:func:) # along with the classname/methodname/funcname minus the parameter # part. newnode = domain.resolve_xref( env, refdoc, app.builder, "obj", resolve_target, node, contnode) 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 return newnode def add_stylesheet(app): app.add_stylesheet('sphinx_paramlinks.css') def copy_stylesheet(app, exception): app.info( bold('The name of the builder is: %s' % app.builder.name), nonl=True) if not _is_html(app) or exception: return app.info(bold('Copying sphinx_paramlinks stylesheet... '), nonl=True) source = os.path.abspath(os.path.dirname(__file__)) # the '_static' directory name is hardcoded in # 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') copyfile(os.path.join(source, "sphinx_paramlinks.css"), dest) app.info('done') def build_index(app, doctree): entries = _tempdata(app) 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') app.env.indexentries.pop('_sphinx_paramlinks_index') def setup(app): app.add_transform(LinkParams) # PyXRefRole is what the sphinx Python domain uses to set up # role nodes like "meth", "func", etc. It produces a "pending xref" # 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) sphinx-paramlinks-0.3.2/sphinx_paramlinks/__init__.py0000644000175000017500000000010412714427532024115 0ustar classicclassic00000000000000__version__ = '0.3.2' from .sphinx_paramlinks import setup # noqa sphinx-paramlinks-0.3.2/LICENSE0000644000175000017500000000215512260322132017251 0ustar classicclassic00000000000000This is the MIT license: http://www.opensource.org/licenses/mit-license.php Copyright (C) by Michael Bayer. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. sphinx-paramlinks-0.3.2/setup.cfg0000664000175000017500000000007312714427644020106 0ustar classicclassic00000000000000[egg_info] tag_build = tag_date = 0 tag_svn_revision = 0