1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
# Kenozooid - software stack to support different capabilities of dive
# computers.
#
# Copyright (C) 2009 by Artur Wroblewski <wrobell@pld-linux.org>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
# Modifications by PAB to override reference text
import os.path
from docutils import nodes
import sys
import re
__Reference_re = re.compile('\s*(.*)\s+<(.*)>\s*$', re.MULTILINE + re.DOTALL)
def api_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
"""
Role `:api:` bridges generated API documentation by tool like EpyDoc
with Sphinx Python Documentation Generator.
Other tools, other than EpyDoc, can be easily supported as well.
First generate the documentation to be referenced, i.e. with EpyDoc::
$ mkdir -p doc/html/api
$ epydoc -o doc/html/api ...
Next step is to generate documentation with Sphinx::
$ sphinx-build doc doc/html
"""
basedir = 'api'
prefix = 'html/' # fixme: fetch it from configuration
exists = lambda f: os.path.exists(prefix + f)
# assume module is references
#print 'Text "%s"' % (text,)
mo = __Reference_re.match(text)
label = None
if mo is not None:
( label, text ) = mo.group(1, 2)
name = text.strip()
uri = file = '%s/%s-module.html' % (basedir, text)
chunks = text.split('.')
#print 'Trying module file %s' % (file,)
# if not module, then a class
if not exists(file):
name = text.split('.')[-1]
uri = file = '%s/%s-class.html' % (basedir, text)
#print 'Trying class file %s' % (file,)
# if not a class, then function or class method
if not exists(file):
method = chunks[-1]
fprefix = '.'.join(chunks[:-1])
# assume function is referenced
file = '%s/%s-module.html' % (basedir, fprefix)
#print 'Trying method file %s' % (file,)
if exists(file):
uri = '%s#%s' % (file, method)
else:
# class method is references
file = '%s/%s-class.html' % (basedir, fprefix)
if exists(file):
name = '.'.join(chunks[-2:]) # name should be Class.method
uri = '%s/%s-class.html#%s' % (basedir, fprefix, method)
if label is None:
label = name
if exists(file):
node = nodes.reference(rawtext, label, refuri=uri, **options)
else:
# cannot find reference, then just inline the text
print 'WARNING: Unable to find %s in API' % (text,)
node = nodes.literal(rawtext, text)
return [node], []
def ticket_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
"""
Role `:ticket:` generates references to Trac tickets.
"""
trac_root = 'https://sourceforge.net/apps/trac/pyxb'
# assume module is references
#print 'Text "%s"' % (text,)
mo = __Reference_re.match(text)
label = None
if mo is not None:
( label, text ) = mo.group(1, 2)
ticket = text.strip()
uri = '%s/ticket/%s' % (trac_root, ticket)
if label is None:
label = '#%s' % (ticket,)
node = nodes.reference(rawtext, label, refuri=uri, **options)
return [node], []
def pyex_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
"""
Role `:pyex:` generates reference to Python exception classes.
"""
pyex_fmt = 'http://docs.python.org/library/exceptions.html#exceptions.%s'
mo = __Reference_re.match(text)
label = None
if mo is not None:
( label, text ) = mo.group(1, 2)
exc = text.strip()
print 'Python exception %s as %s' % (text, label)
uri = pyex_fmt % (exc,)
if label is None:
label = '%s' % (exc,)
node = nodes.reference(rawtext, label, refuri=uri, **options)
return [node], []
def setup(app):
app.add_role('api', api_role)
app.add_config_value('epydoc_basedir', 'api', False)
app.add_config_value('epydoc_prefix', 'doc/html/', False)
app.add_role('ticket', ticket_role)
app.add_config_value('epydoc_track_root', 'http://sourceforge.net/apps/track/project', False)
app.add_role('pyex', pyex_role)
|
