rngdoc.py 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217
  1. #!/usr/bin/env python3
  2. #
  3. # The Qubes OS Project, https://www.qubes-os.org/
  4. #
  5. # Copyright (C) 2014-2015 Joanna Rutkowska <joanna@invisiblethingslab.com>
  6. # Copyright (C) 2014-2015 Wojtek Porczyk <woju@invisiblethingslab.com>
  7. #
  8. # This library is free software; you can redistribute it and/or
  9. # modify it under the terms of the GNU Lesser General Public
  10. # License as published by the Free Software Foundation; either
  11. # version 2.1 of the License, or (at your option) any later version.
  12. #
  13. # This library is distributed in the hope that it will be useful,
  14. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16. # Lesser General Public License for more details.
  17. #
  18. # You should have received a copy of the GNU Lesser General Public
  19. # License along with this library; if not, see <https://www.gnu.org/licenses/>.
  20. #
  21. from __future__ import print_function
  22. import sys
  23. import textwrap
  24. import lxml.etree
  25. class Element:
  26. def __init__(self, schema, xml):
  27. self.schema = schema
  28. self.xml = xml
  29. @property
  30. def nsmap(self):
  31. return self.schema.nsmap
  32. @property
  33. def name(self):
  34. return self.xml.get('name')
  35. def get_description(self, xml=None, wrap=True):
  36. if xml is None:
  37. xml = self.xml
  38. xml = xml.xpath('./doc:description', namespaces=self.nsmap)
  39. if not xml:
  40. return ''
  41. xml = xml[0]
  42. if wrap:
  43. return ''.join(self.schema.wrapper.fill(p) + '\n\n'
  44. for p in textwrap.dedent(xml.text.strip('\n')).split('\n\n'))
  45. return ' '.join(xml.text.strip().split())
  46. def get_data_type(self, xml=None):
  47. if xml is None:
  48. xml = self.xml
  49. value = xml.xpath('./rng:value', namespaces=self.nsmap)
  50. if value:
  51. value = '``{}``'.format(value[0].text.strip())
  52. else:
  53. metavar = xml.xpath('./doc:metavar', namespaces=self.nsmap)
  54. if metavar:
  55. value = '``{}``'.format(metavar[0].text.strip())
  56. else:
  57. value = ''
  58. xml = xml.xpath('./rng:data', namespaces=self.nsmap)
  59. if not xml:
  60. return ('', value)
  61. xml = xml[0]
  62. type_ = xml.get('type', '')
  63. if not value:
  64. pattern = xml.xpath('./rng:param[@name="pattern"]',
  65. namespaces=self.nsmap)
  66. if pattern:
  67. value = '``{}``'.format(pattern[0].text.strip())
  68. return type_, value
  69. def get_attributes(self):
  70. for xml in self.xml.xpath('''./rng:attribute |
  71. ./rng:optional/rng:attribute |
  72. ./rng:choice/rng:attribute''', namespaces=self.nsmap):
  73. required = 'yes' if xml.getparent() == self.xml else 'no'
  74. yield (xml, required)
  75. def resolve_ref(self, ref):
  76. refs = self.xml.xpath(
  77. '//rng:define[name="{}"]/rng:element'.format(ref['name']))
  78. return refs[0] if refs else None
  79. def get_child_elements(self):
  80. for xml in self.xml.xpath('''./rng:element | ./rng:ref |
  81. ./rng:optional/rng:element | ./rng:optional/rng:ref |
  82. ./rng:zeroOrMore/rng:element | ./rng:zeroOrMore/rng:ref |
  83. ./rng:oneOrMore/rng:element | ./rng:oneOrMore/rng:ref''',
  84. namespaces=self.nsmap):
  85. parent = xml.getparent()
  86. qname = lxml.etree.QName(parent)
  87. if parent == self.xml:
  88. number = '1'
  89. elif qname.localname == 'optional':
  90. number = '?'
  91. elif qname.localname == 'zeroOrMore':
  92. number = '\\*'
  93. elif qname.localname == 'oneOrMore':
  94. number = '\\+'
  95. else:
  96. print(parent.tag)
  97. if xml.tag == 'ref':
  98. xml = self.resolve_ref(xml)
  99. if xml is None:
  100. continue
  101. yield (self.schema.elements[xml.get('name')], number)
  102. def write_rst(self, stream):
  103. stream.write('.. _qubesxml-element-{}:\n\n'.format(self.name))
  104. stream.write(make_rst_section('Element: **{}**'.format(self.name), '-'))
  105. stream.write(self.get_description())
  106. attrtable = []
  107. for attr, required in self.get_attributes():
  108. type_, value = self.get_data_type(attr)
  109. attrtable.append((
  110. attr.get('name'),
  111. required,
  112. type_,
  113. value,
  114. self.get_description(attr, wrap=False)))
  115. if attrtable:
  116. stream.write(make_rst_section('Attributes', '^'))
  117. write_rst_table(stream, attrtable,
  118. ('attribute', 'req.', 'type', 'value', 'description'))
  119. childtable = [(':ref:`{0} <qubesxml-element-{0}>`'.format(
  120. child.xml.get('name')), n)
  121. for child, n in self.get_child_elements()]
  122. if childtable:
  123. stream.write(make_rst_section('Child elements', '^'))
  124. write_rst_table(stream, childtable, ('element', 'number'))
  125. class Schema:
  126. # pylint: disable=too-few-public-methods
  127. nsmap = {
  128. 'rng': 'http://relaxng.org/ns/structure/1.0',
  129. 'q': 'http://qubes-os.org/qubes/3',
  130. 'doc': 'http://qubes-os.org/qubes-doc/1'}
  131. def __init__(self, xml):
  132. self.xml = xml
  133. self.wrapper = textwrap.TextWrapper(width=80,
  134. break_long_words=False, break_on_hyphens=False)
  135. self.elements = {}
  136. for node in self.xml.xpath('//rng:element', namespaces=self.nsmap):
  137. element = Element(self, node)
  138. self.elements[element.name] = element
  139. def make_rst_section(heading, char):
  140. return '{}\n{}\n\n'.format(heading, char[0] * len(heading))
  141. def write_rst_table(stream, itr, heads):
  142. stream.write('.. csv-table::\n')
  143. stream.write(' :header: {}\n'.format(', '.join('"{}"'.format(c)
  144. for c in heads)))
  145. stream.write(' :widths: {}\n\n'.format(', '.join('1'
  146. for c in heads)))
  147. for row in itr:
  148. stream.write(' {}\n'.format(', '.join('"{}"'.format(i) for i in row)))
  149. stream.write('\n')
  150. def main(filename, example):
  151. schema = Schema(lxml.etree.parse(open(filename, 'rb')))
  152. sys.stdout.write(make_rst_section('Qubes XML specification', '='))
  153. sys.stdout.write('''
  154. This is the documentation of qubes.xml autogenerated from RelaxNG source.
  155. Quick example, worth thousands lines of specification:
  156. .. literalinclude:: {}
  157. :language: xml
  158. '''[1:].format(example))
  159. for name in sorted(schema.elements):
  160. schema.elements[name].write_rst(sys.stdout)
  161. if __name__ == '__main__':
  162. # pylint: disable=no-value-for-parameter
  163. main(*sys.argv[1:])
  164. # vim: ts=4 sw=4 et