def __init__(self, session, obj, command_table, arg_table):
self.session = session
self.obj = obj
if command_table is None:
command_table = {}
self.command_table = command_table
if arg_table is None:
arg_table = {}
self.arg_table = arg_table
self._subcommand_table = {}
self._related_items = []
self.renderer = get_renderer()
self.doc = ReSTDocument(target='man')
def test_write_py_doc_string(self):
style = ReSTStyle(ReSTDocument())
docstring = ('This describes a function\n'
':param foo: Describes foo\n'
'returns: None')
style.write_py_doc_string(docstring)
self.assertEqual(style.doc.getvalue(), docstring.encode() + b'\n')
def test_toctree_man(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.toctree()
style.tocitem('foo')
style.tocitem('bar')
self.assertEqual(style.doc.getvalue(), b'\n\n\n* foo\n\n\n* bar\n\n')
def test_escape_href_link(self):
style = ReSTStyle(ReSTDocument())
style.start_a(attrs=[('href', 'http://example.org')])
style.doc.write('foo: the next bar')
style.end_a()
self.assertEqual(style.doc.getvalue(),
b'`foo\\: the next bar <http://example.org>`__ ')
def test_href_link(self):
style = ReSTStyle(ReSTDocument())
style.start_a(attrs=[('href', 'http://example.org')])
style.doc.write('example')
style.end_a()
self.assertEqual(style.doc.getvalue(),
b'`example <http://example.org>`__ ')
def test_hidden_toctree_non_html(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.hidden_toctree()
style.hidden_tocitem('foo')
style.hidden_tocitem('bar')
self.assertEqual(style.doc.getvalue(), b'')
def test_examples(self):
style = ReSTStyle(ReSTDocument())
self.assertTrue(style.doc.keep_data)
style.start_examples()
self.assertFalse(style.doc.keep_data)
style.end_examples()
self.assertTrue(style.doc.keep_data)
def test_new_line(self):
style = ReSTStyle(ReSTDocument())
style.new_line()
self.assertEqual(style.doc.getvalue(), b'\n')
style.do_p = False
style.new_line()
self.assertEqual(style.doc.getvalue(), b'\n\n')
def test_hidden_toctree_html(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'html'
style.hidden_toctree()
style.hidden_tocitem('foo')
style.hidden_tocitem('bar')
self.assertEqual(
style.doc.getvalue(),
b'\n.. toctree::\n :maxdepth: 1\n :hidden:\n\n foo\n bar\n')
def create_help_command(self):
help_command = mock.Mock()
help_command.doc = ReSTDocument()
help_command.event_class = 'custom'
help_command.arg_table = {}
operation_model = mock.Mock()
operation_model.documentation = 'description'
operation_model.service_model.operation_names = []
help_command.obj = operation_model
return help_command
def get_help_docs_for_argument(self, shape):
arg_table = {'arg-name': mock.Mock(argument_model=shape)}
help_command = mock.Mock()
help_command.doc = ReSTDocument()
help_command.event_class = 'custom'
help_command.arg_table = arg_table
operation_model = mock.Mock()
operation_model.service_model.operation_names = []
help_command.obj = operation_model
operation_handler = OperationDocumentEventHandler(help_command)
operation_handler.doc_option('arg-name', help_command)
return help_command.doc.getvalue().decode('utf-8')
def test_non_top_level_lists_are_indented(self):
style = ReSTStyle(ReSTDocument())
# Start the top level list
style.start_ul()
# Write one list element
style.start_li()
style.doc.handle_data('foo')
style.end_li()
self.assertEqual(style.doc.getvalue(), b"\n\n\n* foo\n")
# Start the nested list
style.start_ul()
# Write an element to the nested list
style.start_li()
style.doc.handle_data('bar')
style.end_li()
self.assertEqual(style.doc.getvalue(),
b"\n\n\n* foo\n\n\n \n * bar\n ")
def test_external_link(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'html'
style.external_link('MyLink', 'http://example.com/foo')
self.assertEqual(style.doc.getvalue(),
b'`MyLink <http://example.com/foo>`_')
def test_h3(self):
style = ReSTStyle(ReSTDocument())
style.h3('foobar fiebaz')
self.assertEqual(
style.doc.getvalue(),
b'\n\n-------------\nfoobar fiebaz\n-------------\n\n')
def test_empty_code(self):
style = ReSTStyle(ReSTDocument())
style.start_code()
style.end_code()
self.assertEqual(style.doc.getvalue(), b'')
def test_code(self):
style = ReSTStyle(ReSTDocument())
style.code('foobar')
self.assertEqual(style.doc.getvalue(), b'``foobar`` ')
def test_p(self):
style = ReSTStyle(ReSTDocument())
style.start_p()
style.doc.write('foo')
style.end_p()
self.assertEqual(style.doc.getvalue(), b'\n\nfoo\n\n')
def test_italics(self):
style = ReSTStyle(ReSTDocument())
style.italics('foobar')
self.assertEqual(style.doc.getvalue(), b'*foobar* ')
def test_sphinx_py_attr(self):
style = ReSTStyle(ReSTDocument())
style.start_sphinx_py_attr('Foo')
style.end_sphinx_py_attr()
self.assertEqual(style.doc.getvalue(),
b'\n\n.. py:attribute:: Foo\n\n \n\n')
def test_add_links(self):
doc = ReSTDocument()
doc.hrefs['foo'] = 'https://example.com/'
self.assertEqual(doc.getvalue(),
b'\n\n.. _foo: https://example.com/\n')
def test_include_doc_string(self):
doc = ReSTDocument()
doc.include_doc_string('<p>this is a <code>test</code></p>')
self.assertEqual(doc.getvalue(), b'\n\nthis is a ``test`` \n\n')
def test_list(self):
style = ReSTStyle(ReSTDocument())
style.li('foo')
self.assertEqual(style.doc.getvalue(), b'\n* foo\n\n')
class HelpCommand(object):
"""
HelpCommand Interface
---------------------
A HelpCommand object acts as the interface between objects in the
CLI (e.g. Providers, Services, Operations, etc.) and the documentation
system (bcdoc).
A HelpCommand object wraps the object from the CLI space and provides
a consistent interface to critical information needed by the
documentation pipeline such as the object's name, description, etc.
The HelpCommand object is passed to the component of the
documentation pipeline that fires documentation events. It is
then passed on to each document event handler that has registered
for the events.
All HelpCommand objects contain the following attributes:
+ ``session`` - A ``botocore`` ``Session`` object.
+ ``obj`` - The object that is being documented.
+ ``command_table`` - A dict mapping command names to
callable objects.
+ ``arg_table`` - A dict mapping argument names to callable objects.
+ ``doc`` - A ``Document`` object that is used to collect the
generated documentation.
In addition, please note the `properties` defined below which are
required to allow the object to be used in the document pipeline.
Implementations of HelpCommand are provided here for Provider,
Service and Operation objects. Other implementations for other
types of objects might be needed for customization in plugins.
As long as the implementations conform to this basic interface
it should be possible to pass them to the documentation system
and generate interactive and static help files.
"""
EventHandlerClass = None
"""
Each subclass should define this class variable to point to the
EventHandler class used by this HelpCommand.
"""
def __init__(self, session, obj, command_table, arg_table):
self.session = session
self.obj = obj
if command_table is None:
command_table = {}
self.command_table = command_table
if arg_table is None:
arg_table = {}
self.arg_table = arg_table
self._subcommand_table = {}
self._related_items = []
self.renderer = get_renderer()
self.doc = ReSTDocument(target='man')
@property
def event_class(self):
"""
Return the ``event_class`` for this object.
The ``event_class`` is used by the documentation pipeline
when generating documentation events. For the event below::
doc-title.<event_class>.<name>
The document pipeline would use this property to determine
the ``event_class`` value.
"""
pass
@property
def name(self):
"""
Return the name of the wrapped object.
This would be called by the document pipeline to determine
the ``name`` to be inserted into the event, as shown above.
"""
pass
@property
def subcommand_table(self):
"""These are the commands that may follow after the help command"""
return self._subcommand_table
@property
def related_items(self):
"""This is list of items that are related to the help command"""
return self._related_items
def __call__(self, args, parsed_globals):
if args:
subcommand_parser = ArgTableArgParser({}, self.subcommand_table)
parsed, remaining = subcommand_parser.parse_known_args(args)
if getattr(parsed, 'subcommand', None) is not None:
return self.subcommand_table[parsed.subcommand](remaining,
parsed_globals)
# Create an event handler for a Provider Document
instance = self.EventHandlerClass(self)
# Now generate all of the events for a Provider document.
# We pass ourselves along so that we can, in turn, get passed
# to all event handlers.
docevents.generate_events(self.session, self)
self.renderer.render(self.doc.getvalue())
instance.unregister()
def test_external_link_in_man_page(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.external_link('MyLink', 'http://example.com/foo')
self.assertEqual(style.doc.getvalue(), b'MyLink')
def test_writeln(self):
doc = ReSTDocument()
doc.writeln('foo')
self.assertEqual(doc.getvalue(), b'foo\n')
def test_internal_link(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'html'
style.internal_link('MyLink', '/index')
self.assertEqual(style.doc.getvalue(), b':doc:`MyLink </index>`')
def test_remove_doc_string(self):
doc = ReSTDocument()
doc.writeln('foo')
doc.include_doc_string('<p>this is a <code>test</code></p>')
doc.remove_last_doc_string()
self.assertEqual(doc.getvalue(), b'foo\n')
def test_internal_link_in_man_page(self):
style = ReSTStyle(ReSTDocument())
style.doc.target = 'man'
style.internal_link('MyLink', '/index')
self.assertEqual(style.doc.getvalue(), b'MyLink')
def parse(self, html):
docstring_parser = parser.DocStringParser(ReSTDocument())
docstring_parser.feed(html)
docstring_parser.close()
return docstring_parser.doc.getvalue()
def test_bold(self):
style = ReSTStyle(ReSTDocument())
style.bold('foobar')
self.assertEqual(style.doc.getvalue(), b'**foobar** ')
