1 #!/usr/bin/env python
\r
3 # Author: Daniele Varrazzo
\r
4 # Contact: daniele dot varrazzo at gmail dot com
\r
5 # Revision: $Revision$
\r
7 # Copyright: This module has been placed in the public domain.
\r
10 A minimal front end to the Docutils Publisher, producing HTML.
\r
12 Output can refer to Epydoc-generated APIs through the iterpreted text role
\r
19 # The url fragment where the api "index.html" resides w.r.t. the generated docs
\r
24 locale.setlocale(locale.LC_ALL, '')
\r
28 from docutils.core import publish_cmdline, default_description
\r
29 from docutils.parsers.rst.roles import register_canonical_role
\r
30 from docutils import nodes, utils
\r
32 # api references are searched for in these modules
\r
35 'psycopg2._psycopg',
\r
36 'psycopg2.extensions',
\r
39 # name starting with a dot are looking as those objects attributes.
41 # module_name, object_name
42 ('psycopg2.extensions', 'connection'),
43 ('psycopg2.extensions', 'cursor'),
46 # import all the referenced modules
\r
47 for modname in api_modules:
\r
51 """Representation of an element language."""
\r
52 def __init__(self, name, element):
\r
55 # The python object described
\r
56 self.element = element
\r
58 # The base name of the page
\r
62 self.fragment = None
\r
65 # is it a private element?
\r
66 components = self.page.split('.')
\r
67 if self.fragment: components.append(self.fragment)
\r
69 for component in components:
\r
70 if component.startswith('_'):
\r
76 ref = api_root + (private and "private/" or "public/") \
\r
77 + self.page + "-" + self.get_type() + ".html"
\r
79 ref = ref + "#" + self.fragment
\r
84 # detect the element type
\r
85 if isinstance(self.element, types.TypeType):
\r
87 elif isinstance(self.element, types.ModuleType):
\r
90 raise ValueError("Can't choose a type for '%s'." % self.name)
\r
92 def filter_par(name):
\r
93 """Filter parenthesis away from a name."""
\r
94 if name.endswith(")"):
\r
95 return name.split("(")[0]
\r
99 def get_element_target(name):
\r
100 """Return the life, the death, the miracles about a package element."""
\r
102 name = filter_par(name)
\r
104 if name.startswith('.'):
105 for modname, objname in searched_objects:
106 if hasattr(getattr(sys.modules[modname], objname), name[1:]):
107 name = objname + name
110 # is the element a module?
\r
111 if name in api_modules:
\r
112 out = EpydocTarget(name, sys.modules[name])
\r
116 # look for the element in some module
\r
117 for modname in api_modules:
\r
118 element = getattr(sys.modules[modname], name, None)
\r
119 if element is not None:
\r
121 # Check if it is a function defined in a module
\r
122 if isinstance(element,
\r
123 (int, types.FunctionType, types.BuiltinFunctionType)):
\r
124 out = EpydocTarget(name, sys.modules[modname])
\r
126 out.fragment = name
\r
128 out = EpydocTarget(name, element)
\r
129 out.page = modname + '.' + name
\r
133 # maybe a qualified name?
\r
135 out = get_element_target('.'.join(name.split('.')[:-1]))
\r
136 if out is not None:
\r
137 out.fragment = filter_par(name.split('.')[-1])
\r
140 raise ValueError("Can't find '%s' in any provided module." % name)
\r
142 def api_role(role, rawtext, text, lineno, inliner,
143 options={}, content=[]):
\r
145 target = get_element_target(text)
\r
146 except Exception, exc:
\r
147 msg = inliner.reporter.error(str(exc), line=lineno)
148 prb = inliner.problematic(rawtext, rawtext, msg)
151 ref = target.get_url()
\r
152 node2 = nodes.literal(rawtext, utils.unescape(text))
153 node = nodes.reference(rawtext, '', node2, refuri=ref,
\r
158 register_canonical_role('api', api_role)
160 # Register the 'api' role as canonical role
161 from docutils.parsers.rst import roles
162 roles.DEFAULT_INTERPRETED_ROLE = 'api'
165 description = ('Generates (X)HTML documents from standalone reStructuredText '
\r
166 'sources with links to Epydoc API. ' + default_description)
\r
169 publish_cmdline(writer_name='html', description=description)
\r