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