--- /dev/null
+#!/usr/bin/env python\r
+\r
+# Author: Daniele Varrazzo\r
+# Contact: daniele dot varrazzo at gmail dot com\r
+# Revision: $Revision$\r
+# Date: $Date$\r
+# Copyright: This module has been placed in the public domain.\r
+\r
+"""\r
+A minimal front end to the Docutils Publisher, producing HTML.\r
+\r
+Output can refer to Epydoc-generated APIs through the iterpreted text role\r
+"api".\r
+"""\r
+\r
+import types\r
+import sys\r
+\r
+# The url fragment where the api "index.html" resides w.r.t. the generated docs\r
+api_root = "api/"\r
+\r
+try:\r
+ import locale\r
+ locale.setlocale(locale.LC_ALL, '')\r
+except:\r
+ pass\r
+\r
+from docutils.core import publish_cmdline, default_description\r
+from docutils.parsers.rst.roles import register_canonical_role\r
+from docutils import nodes, utils\r
+\r
+# api references are searched for in these modules\r
+api_modules = [\r
+ 'psycopg2',\r
+ 'psycopg2._psycopg',\r
+ 'psycopg2.extensions',\r
+]\r
+\r
+# name starting with a dot are looking as those objects attributes.
+searched_objects = [
+ # module_name, object_name
+ ('psycopg2.extensions', 'connection'),
+ ('psycopg2.extensions', 'cursor'),
+]
+
+# import all the referenced modules\r
+for modname in api_modules:\r
+ __import__(modname)\r
+ \r
+class EpydocTarget:
+ """Representation of an element language."""\r
+ def __init__(self, name, element):\r
+ self.name = name\r
+ \r
+ # The python object described\r
+ self.element = element\r
+ \r
+ # The base name of the page\r
+ self.page = None\r
+ \r
+ # The url fragment\r
+ self.fragment = None\r
+ \r
+ def get_url(self):\r
+ # is it a private element?\r
+ components = self.page.split('.')\r
+ if self.fragment: components.append(self.fragment)\r
+ \r
+ for component in components:\r
+ if component.startswith('_'):\r
+ private = True\r
+ break\r
+ else:\r
+ private = False\r
+ \r
+ ref = api_root + (private and "private/" or "public/") \\r
+ + self.page + "-" + self.get_type() + ".html"\r
+ if self.fragment:\r
+ ref = ref + "#" + self.fragment\r
+ \r
+ return ref\r
+\r
+ def get_type(self):\r
+ # detect the element type\r
+ if isinstance(self.element, types.TypeType):\r
+ return 'class'\r
+ elif isinstance(self.element, types.ModuleType):\r
+ return 'module'\r
+ else:\r
+ raise ValueError("Can't choose a type for '%s'." % self.name)\r
+ \r
+def filter_par(name):\r
+ """Filter parenthesis away from a name."""\r
+ if name.endswith(")"):\r
+ return name.split("(")[0]\r
+ else:\r
+ return name\r
+ \r
+def get_element_target(name):\r
+ """Return the life, the death, the miracles about a package element."""\r
+ \r
+ name = filter_par(name)\r
+
+ if name.startswith('.'):
+ for modname, objname in searched_objects:
+ if hasattr(getattr(sys.modules[modname], objname), name[1:]):
+ name = objname + name
+ break
+ \r
+ # is the element a module?\r
+ if name in api_modules:\r
+ out = EpydocTarget(name, sys.modules[name])\r
+ out.page = name\r
+ return out\r
+ \r
+ # look for the element in some module\r
+ for modname in api_modules:\r
+ element = getattr(sys.modules[modname], name, None)\r
+ if element is not None:\r
+ \r
+ # Check if it is a function defined in a module\r
+ if isinstance(element, \r
+ (int, types.FunctionType, types.BuiltinFunctionType)):\r
+ out = EpydocTarget(name, sys.modules[modname])\r
+ out.page = modname\r
+ out.fragment = name\r
+ else:\r
+ out = EpydocTarget(name, element)\r
+ out.page = modname + '.' + name\r
+ \r
+ return out\r
+ \r
+ # maybe a qualified name?\r
+ if '.' in name:\r
+ out = get_element_target('.'.join(name.split('.')[:-1]))\r
+ if out is not None:\r
+ out.fragment = filter_par(name.split('.')[-1])\r
+ return out\r
+ \r
+ raise ValueError("Can't find '%s' in any provided module." % name)\r
+ \r
+def api_role(role, rawtext, text, lineno, inliner,
+ options={}, content=[]):\r
+ try:\r
+ target = get_element_target(text)\r
+ except Exception, exc:\r
+ msg = inliner.reporter.error(str(exc), line=lineno)
+ prb = inliner.problematic(rawtext, rawtext, msg)
+ return [prb], [msg]
+ \r
+ ref = target.get_url()\r
+ node2 = nodes.literal(rawtext, utils.unescape(text))
+ node = nodes.reference(rawtext, '', node2, refuri=ref,\r
+ **options)\r
+ return [node], []
+\r
+
+register_canonical_role('api', api_role)
+\r
+# Register the 'api' role as canonical role
+from docutils.parsers.rst import roles
+roles.DEFAULT_INTERPRETED_ROLE = 'api'
+\r
+
+description = ('Generates (X)HTML documents from standalone reStructuredText '\r
+ 'sources with links to Epydoc API. ' + default_description)\r
+\r
+
+publish_cmdline(writer_name='html', description=description)\r
git://git.onelab.eu / plcapi.git / blobdiff