[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [bridgedb/master] Link twisted.* Sphinx directives to Twisted API docs.



commit 23d30237937e15dda01d25970c902e077f5ebde1
Author: Isis Lovecruft <isis@xxxxxxxxxxxxxx>
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):



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits