[tor-commits] [bridgedb/master] Link twisted.* Sphinx directives to Twisted API docs.
isis at torproject.org
isis at torproject.org
Sun Jan 12 06:06:33 UTC 2014
commit 23d30237937e15dda01d25970c902e077f5ebde1
Author: Isis Lovecruft <isis at torproject.org>
Date: Thu Nov 28 12:05:24 2013 +0000
Link twisted.* Sphinx directives to Twisted API docs.
---
doc/sphinx/ext/apilinks_sphinxext.py | 54 ++++++++++++++++++++++++++++++++++
doc/sphinx/source/conf.py | 7 ++++-
lib/bridgedb/HTTPServer.py | 2 +-
lib/bridgedb/Main.py | 2 +-
lib/bridgedb/parse/headers.py | 2 +-
lib/bridgedb/parse/options.py | 2 +-
lib/bridgedb/test/util.py | 2 +-
7 files changed, 65 insertions(+), 6 deletions(-)
diff --git a/doc/sphinx/ext/apilinks_sphinxext.py b/doc/sphinx/ext/apilinks_sphinxext.py
new file mode 100644
index 0000000..0f26b61
--- /dev/null
+++ b/doc/sphinx/ext/apilinks_sphinxext.py
@@ -0,0 +1,54 @@
+'''
+Sphinx/docutils extension to create links to pyDoctor documentation using
+a RestructuredText interpreted text role that looks like this:
+
+ :api:`python_object_to_link_to <label>`
+
+for example:
+
+ :api:`twisted.internet.defer.Deferred <Deferred>`
+
+Note, this is downloaded from:
+
+ https://bazaar.launchpad.net/~khorn/pydoctor/sphinxext/view/head:/apilinks_sphinxext.py
+
+with a couple local tweaks ("label = full_name" and https for URL).
+'''
+
+def make_api_link(name, rawtext, text, lineno, inliner,
+ options={}, content=[]):
+
+ from docutils import nodes, utils
+
+ # quick, dirty, and ugly...
+ if '<' in text and '>' in text:
+ full_name, label = text.split('<')
+ full_name = full_name.strip()
+ label = label.strip('>').strip()
+ else:
+ full_name = text
+ label = full_name
+
+ #get the base url for api links from the config file
+ env = inliner.document.settings.env
+ base_url = env.config.apilinks_base_url
+
+ # not really sufficient, but just testing...
+ # ...hmmm, maybe this is good enough after all
+ ref = ''.join((base_url, full_name, '.html'))
+
+ node = nodes.reference(rawtext, utils.unescape(label), refuri=ref,
+ **options)
+
+ nodes = [node]
+ sys_msgs = []
+ return nodes, sys_msgs
+
+
+# setup function to register the extension
+
+def setup(app):
+ app.add_config_value('apilinks_base_url',
+ 'https://twistedmatrix.com/documents/current/api/',
+ 'env')
+ app.add_role('api', make_api_link)
diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py
index 187bf49..ab47a43 100644
--- a/doc/sphinx/source/conf.py
+++ b/doc/sphinx/source/conf.py
@@ -22,6 +22,9 @@ sys.path.insert(0, os.path.abspath(os.path.join(
'..', '..', '..', 'lib', 'bridgedb')))
sys.path.insert(0, os.path.abspath(os.path.join(
'..', '..', '..', 'scripts')))
+sys.path.insert(0, os.path.abspath(os.path.join(
+ '..', 'ext')))
+
import bridgedb
import bridgedb.Bridges
@@ -43,6 +46,7 @@ import bridgedb.Tests
import bridgedb.Util
import gen_bridge_descriptors
+
class Mock(object):
"""Used to fake the presence of Python C-extensions for documentation
building. See
@@ -93,7 +97,8 @@ extensions = ['sphinx.ext.autodoc',
'sphinx.ext.pngmath',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
- 'sphinx.ext.viewcode']
+ 'sphinx.ext.viewcode',
+ 'apilinks_sphinxext']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']
diff --git a/lib/bridgedb/HTTPServer.py b/lib/bridgedb/HTTPServer.py
index fe4e095..d430aa3 100644
--- a/lib/bridgedb/HTTPServer.py
+++ b/lib/bridgedb/HTTPServer.py
@@ -345,7 +345,7 @@ def setLocaleFromRequestHeader(request):
languages and add them as fallbacks to the first. Lastly, install this
chain of translations.
- :type request: :class:`twisted.web.server.Request`
+ :type request: :api:`twisted.web.server.Request`
:param request: An incoming request from a client.
:rtype: list
:returns: All requested languages.
diff --git a/lib/bridgedb/Main.py b/lib/bridgedb/Main.py
index 8e22719..0a864f2 100644
--- a/lib/bridgedb/Main.py
+++ b/lib/bridgedb/Main.py
@@ -481,7 +481,7 @@ def startup(options):
string to associate with the ``task``, and ``task`` is some
scheduled event, repetitive or otherwise, for the :class:`reactor
<twisted.internet.epollreactor.EPollReactor>`. See the classes
- within the :mod:`twisted.internet.tasks` module.
+ within the :api:`twisted.internet.tasks` module.
"""
logging.debug("Caught SIGHUP")
logging.info("Reloading...")
diff --git a/lib/bridgedb/parse/headers.py b/lib/bridgedb/parse/headers.py
index b47e67b..b557372 100644
--- a/lib/bridgedb/parse/headers.py
+++ b/lib/bridgedb/parse/headers.py
@@ -35,7 +35,7 @@ def parseAcceptLanguage(header):
4. Change all hyphens to underscores.
:param string header: The contents of an 'Accept-Language' header, i.e. as
- if taken from :func:`twisted.web.server.Request.getHeader`.
+ if taken from :api:`twisted.web.server.Request.getHeader`.
:rtype: list
:returns: A list of language codes (with and without locales), in order of
preference.
diff --git a/lib/bridgedb/parse/options.py b/lib/bridgedb/parse/options.py
index d863015..323de6d 100644
--- a/lib/bridgedb/parse/options.py
+++ b/lib/bridgedb/parse/options.py
@@ -164,7 +164,7 @@ class BaseOptions(usage.Options):
:param config: The user-supplied path to the config file, from the
commandline options (i.e.
``options = BaseOptions().parseOptions(); options['config'];``).
- :raises: :exc:`twisted.python.usage.UsageError` if either the runtime
+ :raises: :api:`twisted.python.usage.UsageError` if either the runtime
directory or the config file cannot be found.
"""
gRundir = getRundir()
diff --git a/lib/bridgedb/test/util.py b/lib/bridgedb/test/util.py
index 4520e29..65abd28 100644
--- a/lib/bridgedb/test/util.py
+++ b/lib/bridgedb/test/util.py
@@ -43,7 +43,7 @@ def fileCheckDecorator(func):
:type func: callable
:param func: The ``test_*`` method, from a
- :class:`twisted.trial.unittest.TestCase` instance, to wrap.
+ :api:`twisted.trial.unittest.TestCase` instance, to wrap.
"""
@wraps(func)
def wrapper(self, src, dst, description):
More information about the tor-commits
mailing list