Source Code for Module mrv.doc.extapi

 1  # computers. 
 2  # 
 3  # Copyright (C) 2009 by Artur Wroblewski <wrobell@pld-linux.org> 
 4  # 
 5  # This program is free software: you can redistribute it and/or modify 
 6  # it under the terms of the GNU General Public License as published by 
 7  # the Free Software Foundation, either version 3 of the License, or 
 8  # (at your option) any later version. 
 9  # 
10  # This program is distributed in the hope that it will be useful, 
11  # but WITHOUT ANY WARRANTY; without even the implied warranty of 
12  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
13  # GNU General Public License for more details. 
14  # 
15  # You should have received a copy of the GNU General Public License 
16  # along with this program.  If not, see <http://www.gnu.org/licenses/>. 
17  # 
18   
19  import os.path 
20  from docutils import nodes 
21   
22 -def api_role(role, rawtext, text, lineno, inliner, options={}, content=[]): 
23      """ 
24      Role `:api:` bridges generated API documentation by tool like EpyDoc 
25      with Sphinx Python Documentation Generator. 
26   
27      Other tools, other than EpyDoc, can be easily supported as well. 
28   
29      First generate the documentation to be referenced, i.e. with EpyDoc:: 
30   
31          $ mkdir -p doc/_build/html/api 
32          $ epydoc -o doc/_build/html/api ... 
33   
34      Next step is to generate documentation with Sphinx:: 
35   
36          $ sphinx-build doc doc/_build/html 
37   
38      """ 
39      basedir = 'api' 
40      prefix = 'build/html/generated/' # fixme: fetch it from configuration 
41      exists = lambda f: os.path.exists(prefix + f) 
42   
43      # assume module is references 
44      name = '%s' % text 
45      uri = file = '%s/%s-module.html' % (basedir, text) 
46      chunks = text.split('.') 
47   
48      # if not module, then a class 
49      if not exists(file): 
50          name = text.split('.')[-1] 
51          uri = file = '%s/%s-class.html' % (basedir, text) 
52   
53      # if not a class, then function or class method  
54      if not exists(file): 
55          method = chunks[-1] 
56          fprefix = '.'.join(chunks[:-1]) 
57          # assume function is referenced 
58          file = '%s/%s-module.html' % (basedir, fprefix) 
59          if exists(file): 
60              uri = '%s#%s' % (file, method) 
61          else: 
62              # class method is references 
63              file = '%s/%s-class.html' % (basedir, fprefix) 
64              if exists(file): 
65                  name = '.'.join(chunks[-2:]) # name should be Class.method 
66                  uri = '%s/%s-class.html#%s' % (basedir, fprefix, method) 
67   
68      if exists(file): 
69          name = os.path.basename(uri) 
70          name = name[:name.rfind('-')] 
71          node = nodes.reference(rawtext, "Epydoc: %s" % name, refuri=uri, **options) 
72      else: 
73          # cannot find reference, then just inline the text 
74          node = nodes.literal(rawtext, text) 
75   
76      return [node], [] 
77   
78   
79 -def setup(app): 
80      app.add_role('api', api_role) 
81