dochelpers.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  1. #
  2. # The Qubes OS Project, https://www.qubes-os.org/
  3. #
  4. # Copyright (C) 2010-2015 Joanna Rutkowska <joanna@invisiblethingslab.com>
  5. # Copyright (C) 2014-2015 Wojtek Porczyk <woju@invisiblethingslab.com>
  6. #
  7. # This program is free software; you can redistribute it and/or modify
  8. # it under the terms of the GNU Lesser General Public License as published by
  9. # the Free Software Foundation; either version 2.1 of the License, or
  10. # (at your option) any later version.
  11. #
  12. # This program is distributed in the hope that it will be useful,
  13. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15. # GNU Lesser General Public License for more details.
  16. #
  17. # You should have received a copy of the GNU Lesser General Public License along
  18. # with this program; if not, write to the Free Software Foundation, Inc.,
  19. # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20. #
  21. '''Documentation helpers.
  22. This module contains classes and functions which help to maintain documentation,
  23. particularly our custom Sphinx extension.
  24. '''
  25. import argparse
  26. import io
  27. import os
  28. import re
  29. import docutils
  30. import docutils.nodes
  31. import docutils.parsers.rst
  32. import docutils.parsers.rst.roles
  33. import docutils.statemachine
  34. import sphinx
  35. import sphinx.errors
  36. import sphinx.locale
  37. import sphinx.util.docfields
  38. import qubesadmin.tools
  39. SUBCOMMANDS_TITLE = 'COMMANDS'
  40. OPTIONS_TITLE = 'OPTIONS'
  41. def make_rst_section(heading, char):
  42. '''Format a section header in rst'''
  43. return '{}\n{}\n\n'.format(heading, char[0] * len(heading))
  44. def prepare_manpage(command):
  45. '''Build a man page skeleton'''
  46. parser = qubesadmin.tools.get_parser_for_command(command)
  47. stream = io.StringIO()
  48. stream.write('.. program:: {}\n\n'.format(command))
  49. stream.write(make_rst_section(
  50. ':program:`{}` -- {}'.format(command, parser.description), '='))
  51. stream.write('''.. warning::
  52. This page was autogenerated from command-line parser. It shouldn't be 1:1
  53. conversion, because it would add little value. Please revise it and add
  54. more descriptive help, which normally won't fit in standard ``--help``
  55. option.
  56. After rewrite, please remove this admonition.\n\n''')
  57. stream.write(make_rst_section('Synopsis', '-'))
  58. usage = ' '.join(parser.format_usage().strip().split())
  59. if usage.startswith('usage: '):
  60. usage = usage[len('usage: '):]
  61. # replace METAVARS with *METAVARS*
  62. usage = re.sub(r'\b([A-Z]{2,})\b', r'*\1*', usage)
  63. stream.write(':command:`{}` {}\n\n'.format(command, usage))
  64. stream.write(make_rst_section('Options', '-'))
  65. for action in parser._actions: # pylint: disable=protected-access
  66. stream.write('.. option:: ')
  67. if action.metavar:
  68. stream.write(', '.join('{}{}{}'.format(
  69. option,
  70. '=' if option.startswith('--') else ' ',
  71. action.metavar)
  72. for option in sorted(action.option_strings)))
  73. else:
  74. stream.write(', '.join(sorted(action.option_strings)))
  75. stream.write('\n\n {}\n\n'.format(action.help))
  76. stream.write(make_rst_section('Authors', '-'))
  77. stream.write('''\
  78. | Joanna Rutkowska <joanna at invisiblethingslab dot com>
  79. | Rafal Wojtczuk <rafal at invisiblethingslab dot com>
  80. | Marek Marczykowski <marmarek at invisiblethingslab dot com>
  81. | Wojtek Porczyk <woju at invisiblethingslab dot com>
  82. .. vim: ts=3 sw=3 et tw=80
  83. ''')
  84. return stream.getvalue()
  85. class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor):
  86. ''' Checks if the visited option nodes and the specified args are in sync.
  87. '''
  88. def __init__(self, command, args, document):
  89. assert isinstance(args, set)
  90. docutils.nodes.SparseNodeVisitor.__init__(self, document)
  91. self.command = command
  92. self.args = args
  93. def visit_desc(self, node):
  94. ''' Skips all but 'option' elements '''
  95. # pylint: disable=no-self-use
  96. if not node.get('desctype', None) == 'option':
  97. raise docutils.nodes.SkipChildren
  98. def visit_desc_name(self, node):
  99. ''' Checks if the option is defined `self.args` '''
  100. if not isinstance(node[0], docutils.nodes.Text):
  101. raise sphinx.errors.SphinxError('first child should be Text')
  102. arg = str(node[0])
  103. try:
  104. self.args.remove(arg)
  105. except KeyError:
  106. raise sphinx.errors.SphinxError(
  107. 'No such argument for {!r}: {!r}'.format(self.command, arg))
  108. def check_undocumented_arguments(self, ignored_options=None):
  109. ''' Call this to check if any undocumented arguments are left.
  110. While the documentation talks about a
  111. 'SparseNodeVisitor.depart_document()' function, this function does
  112. not exists. (For details see implementation of
  113. :py:method:`NodeVisitor.dispatch_departure()`) So we need to
  114. manually call this.
  115. '''
  116. if ignored_options is None:
  117. ignored_options = set()
  118. left_over_args = self.args - ignored_options
  119. if left_over_args:
  120. raise sphinx.errors.SphinxError(
  121. 'Undocumented arguments for command {!r}: {!r}'.format(
  122. self.command, ', '.join(sorted(left_over_args))))
  123. class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor):
  124. ''' Checks if the visited sub command section nodes and the specified sub
  125. command args are in sync.
  126. '''
  127. def __init__(self, command, sub_commands, document):
  128. docutils.nodes.SparseNodeVisitor.__init__(self, document)
  129. self.command = command
  130. self.sub_commands = sub_commands
  131. def visit_section(self, node):
  132. ''' Checks if the visited sub-command section nodes exists and it
  133. options are in sync.
  134. Uses :py:class:`OptionsCheckVisitor` for checking
  135. sub-commands options
  136. '''
  137. # pylint: disable=no-self-use
  138. title = str(node[0][0])
  139. if title.upper() == SUBCOMMANDS_TITLE:
  140. return
  141. sub_cmd = self.command + ' ' + title
  142. try:
  143. args = self.sub_commands[title]
  144. options_visitor = OptionsCheckVisitor(sub_cmd, args, self.document)
  145. node.walkabout(options_visitor)
  146. options_visitor.check_undocumented_arguments(
  147. {'--help', '--quiet', '--verbose', '-h', '-q', '-v'})
  148. del self.sub_commands[title]
  149. except KeyError:
  150. raise sphinx.errors.SphinxError(
  151. 'No such sub-command {!r}'.format(sub_cmd))
  152. def visit_Text(self, node):
  153. ''' If the visited text node starts with 'alias: ', all the provided
  154. comma separted alias in this node, are removed from
  155. `self.sub_commands`
  156. '''
  157. # pylint: disable=invalid-name
  158. text = str(node).strip()
  159. if text.startswith('aliases:'):
  160. aliases = {a.strip() for a in text.split('aliases:')[1].split(',')}
  161. for alias in aliases:
  162. assert alias in self.sub_commands
  163. del self.sub_commands[alias]
  164. def check_undocumented_sub_commands(self):
  165. ''' Call this to check if any undocumented sub_commands are left.
  166. While the documentation talks about a
  167. 'SparseNodeVisitor.depart_document()' function, this function does
  168. not exists. (For details see implementation of
  169. :py:method:`NodeVisitor.dispatch_departure()`) So we need to
  170. manually call this.
  171. '''
  172. if self.sub_commands:
  173. raise sphinx.errors.SphinxError(
  174. 'Undocumented commands for {!r}: {!r}'.format(
  175. self.command, ', '.join(sorted(self.sub_commands.keys()))))
  176. class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor):
  177. ''' Checks if the sub-commands and options specified in the 'COMMAND' and
  178. 'OPTIONS' (case insensitve) sections in sync the command parser.
  179. '''
  180. def __init__(self, app, command, document):
  181. docutils.nodes.SparseNodeVisitor.__init__(self, document)
  182. try:
  183. parser = qubesadmin.tools.get_parser_for_command(command)
  184. except ImportError:
  185. app.warn('cannot import module for command')
  186. self.parser = None
  187. return
  188. except AttributeError:
  189. raise sphinx.errors.SphinxError('cannot find parser in module')
  190. self.command = command
  191. self.parser = parser
  192. self.options = set()
  193. self.sub_commands = {}
  194. self.app = app
  195. # pylint: disable=protected-access
  196. for action in parser._actions:
  197. if action.help == argparse.SUPPRESS:
  198. continue
  199. if issubclass(action.__class__,
  200. qubesadmin.tools.AliasedSubParsersAction):
  201. for cmd, cmd_parser in action._name_parser_map.items():
  202. self.sub_commands[cmd] = set()
  203. for sub_action in cmd_parser._actions:
  204. if sub_action.help != argparse.SUPPRESS:
  205. self.sub_commands[cmd].update(
  206. sub_action.option_strings)
  207. else:
  208. self.options.update(action.option_strings)
  209. def visit_section(self, node):
  210. ''' If section title is OPTIONS or COMMANDS dispatch the apropriate
  211. `NodeVisitor`.
  212. '''
  213. if self.parser is None:
  214. return
  215. section_title = str(node[0][0]).upper()
  216. if section_title == OPTIONS_TITLE:
  217. options_visitor = OptionsCheckVisitor(self.command, self.options,
  218. self.document)
  219. node.walkabout(options_visitor)
  220. options_visitor.check_undocumented_arguments()
  221. elif section_title == SUBCOMMANDS_TITLE:
  222. sub_cmd_visitor = CommandCheckVisitor(
  223. self.command, self.sub_commands, self.document)
  224. node.walkabout(sub_cmd_visitor)
  225. sub_cmd_visitor.check_undocumented_sub_commands()
  226. def check_man_args(app, doctree, docname):
  227. ''' Checks the manpage for undocumented or obsolete sub-commands and
  228. options.
  229. '''
  230. dirname, command = os.path.split(docname)
  231. if os.path.basename(dirname) != 'manpages':
  232. return
  233. app.info('Checking arguments for {!r}'.format(command))
  234. doctree.walk(ManpageCheckVisitor(app, command, doctree))
  235. def break_to_pdb(app, *dummy):
  236. '''DEBUG'''
  237. if not app.config.break_to_pdb:
  238. return
  239. import pdb
  240. pdb.set_trace()
  241. def setup(app):
  242. '''Setup Sphinx extension'''
  243. app.add_config_value('break_to_pdb', False, 'env')
  244. app.connect('doctree-resolved', break_to_pdb)
  245. app.connect('doctree-resolved', check_man_args)
  246. # vim: ts=4 sw=4 et