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
|
# Original code from: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
#
# 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/>.
#
import os.path
from docutils import nodes
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/_build/html/api
$ epydoc -o doc/_build/html/api ...
Next step is to generate documentation with Sphinx::
$ sphinx-build doc doc/_build/html
"""
basedir = 'api'
prefix = '_build/html/' # fixme: fetch it from configuration
exists = lambda f: os.path.exists(prefix + f)
# assume module is references
name = '%s' % text
uri = file = '%s/%s-module.html' % (basedir, text)
chunks = text.split('.')
# if not module, then a class
if not exists(file):
name = text.split('.')[-1]
uri = file = '%s/%s-class.html' % (basedir, text)
# 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)
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 exists(file):
node = nodes.reference(rawtext, name, refuri=uri, **options)
else:
# cannot find reference, then just inline the text
node = nodes.literal(rawtext, text)
return [node], []
def setup(app):
app.add_role('api', api_role)
|
