code.grnet.gr Git - ganeti-local/blob - doc/build-rapi-resources-doc

   1 #!/usr/bin/python
   2 #
   3
   4 # Copyright (C) 2008 Google Inc.
   5 #
   6 # This program is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful, but
  12 # WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 # General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program; if not, write to the Free Software
  18 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 # 02110-1301, USA.
  20
  21 """Script to generate documentation for remote API resources.
  22
  23 This is hard-coded to the section numbering we have in the master RST
  24 document.
  25
  26 """
  27
  28 import re
  29 import cgi
  30 import inspect
  31
  32 from ganeti.rapi import rlib2
  33 from ganeti.rapi import connector
  34
  35
  36 CHECKED_COMMANDS = ["GET", "POST", "PUT", "DELETE"]
  37
  38
  39 def beautify(text):
  40   """A couple of small enhancements, epydoc-to-rst.
  41
  42   """
  43   pairs = [
  44     ("@return:", "Returns:"),
  45     ]
  46
  47   for old, new in pairs:
  48     text = text.replace(old, new)
  49
  50   return text
  51
  52
  53 def indent(text):
  54   """Returns a text block with all lines indented.
  55
  56   """
  57   lines = text.splitlines()
  58   lines = ["  " + l for l in lines]
  59   return "\n".join(lines)
  60
  61
  62 def main():
  63   # Get list of all resources
  64   all = list(connector.CONNECTOR.itervalues())
  65
  66   # Sort rlib by URI
  67   all.sort(cmp=lambda a, b: cmp(a.DOC_URI, b.DOC_URI))
  68
  69   print ".. Automatically generated, do not edit\n"
  70
  71   for cls in all:
  72     title = cls.DOC_URI
  73     print "%s\n%s\n" % (title, "+" * len(title))
  74
  75     # Class docstring
  76     description = inspect.getdoc(cls)
  77     if description:
  78       print "::\n"
  79       print indent(description.strip())
  80     print
  81     supported = [cmd for cmd in CHECKED_COMMANDS if hasattr(cls, cmd)]
  82     print "It supports the following commands: %s." % (", ".join(supported))
  83     print
  84
  85     for cmd in CHECKED_COMMANDS:
  86       if not hasattr(cls, cmd):
  87         continue
  88
  89       print "%s\n%s\n" % (cmd, "~" * len(cmd))
  90
  91       # Get docstring
  92       text = inspect.getdoc(getattr(cls, cmd))
  93       if text:
  94         text = beautify(text)
  95         print "::\n"
  96         print indent(text)
  97         print
  98
  99
 100 if __name__ == "__main__":
 101   main()