def html_to_rst(html, indent=0, indent_first=False):
    """
    Use bcdoc to convert html to rst.

    :type html: string
    :param html: Input HTML to be converted
    :type indent: int
    :param indent: Number of spaces to indent each line
    :type indent_first: boolean
    :param indent_first: Whether to indent the first line
    :rtype: string
    """
    doc = ReSTDocument()

    # TODO: Remove me, temp workaround to fix doc building
    # because of smart quotes that aren't currently supported.
    html = html.replace(u'\u2019', "'")
    html = html.replace(u'\u2014', '-')

    doc.include_doc_string(html)
    rst = doc.getvalue().decode('utf-8')

    if indent:
        rst = '\n'.join([(' ' * indent) + line for line in rst.splitlines()])

        if not indent_first:
            rst = rst.strip()

    return rst
Example #2
0
def html_to_rst(html, indent=0, indent_first=False):
    """
    Use bcdoc to convert html to rst.

    :type html: string
    :param html: Input HTML to be converted
    :type indent: int
    :param indent: Number of spaces to indent each line
    :type indent_first: boolean
    :param indent_first: Whether to indent the first line
    :rtype: string
    """
    doc = ReSTDocument()

    # TODO: Remove me, temp workaround to fix doc building
    # because of smart quotes that aren't currently supported.
    html = html.replace(u'\u2019', "'")
    html = html.replace(u'\u2014', '-')

    doc.include_doc_string(html)
    rst = doc.getvalue().decode('utf-8')

    if indent:
        rst = '\n'.join([(' ' * indent) + line for line in rst.splitlines()])

        if not indent_first:
            rst = rst.strip()

    return rst
Example #3
0
 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.renderer = get_renderer()
     self.doc = ReSTDocument(target='man')
Example #4
0
File: mangle.py Project: Axik/boto3
def html_to_rst(html):
    """
    Converts the service HTML docs to reStructured Text, for use in docstrings.

    :param html: The raw HTML to convert
    :type html: string

    :returns: A reStructured Text formatted version of the text
    :rtype: string
    """
    doc = ReSTDocument()
    doc.include_doc_string(html)
    raw_doc = doc.getvalue()
    return raw_doc.decode('utf-8')
Example #5
0
 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(), six.b(docstring + '\n'))
Example #6
0
 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)
Example #7
0
 def test_sphinx_py_method_with_params(self):
     style = ReSTStyle(ReSTDocument())
     style.start_sphinx_py_method('method', 'foo=None')
     style.end_sphinx_py_method()
     self.assertEqual(
         style.doc.getvalue(),
         six.b('\n\n.. py:method:: method(foo=None)\n\n  \n\n'))
Example #8
0
 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(), six.b(''))
Example #9
0
 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(),
                      six.b('\n\n\n* foo\n\n\n* bar\n\n'))
Example #10
0
 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(),
         six.b('`foo\\: the next bar`_ \n\n.. _foo\\: the next '
               'bar: http://example.org\n'))
Example #11
0
 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(),
         six.b('\n.. toctree::\n  :maxdepth: 1'
               '\n  :hidden:\n\n  foo\n  bar\n'))
Example #12
0
def html_to_rst(html, indent=0, indentFirst=False):
    """
    Use bcdoc to convert html to rst.

    :type html: string
    :param html: Input HTML to be converted
    :type indent: int
    :param indent: Number of spaces to indent each line
    :type indentFirst: boolean
    :param indentFirst: Whether to indent the first line
    :rtype: string
    """
    doc = ReSTDocument()
    doc.include_doc_string(html)
    rst = doc.getvalue().decode('utf-8')

    if indent:
        rst = '\n'.join([(' ' * indent) + line for line in rst.splitlines()])

        if not indentFirst:
            rst = rst.strip()

    return rst
Example #13
0
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.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

    def __call__(self, args, 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.
        bcdoc.docevents.generate_events(self.session, self)
        self.renderer.render(self.doc.getvalue())
        instance.unregister()
Example #14
0
 def test_sphinx_reference_label_html(self):
     style = ReSTStyle(ReSTDocument())
     style.doc.target = 'html'
     style.sphinx_reference_label('foo', 'bar')
     self.assertEqual(style.doc.getvalue(), six.b(':ref:`bar <foo>`'))
Example #15
0
 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(), six.b('foo\n'))
Example #16
0
 def test_include_doc_string(self):
     doc = ReSTDocument()
     doc.include_doc_string('<p>this is a <code>test</code></p>')
     self.assertEqual(doc.getvalue(), six.b('\n\nthis is a ``test`` \n\n'))
Example #17
0
 def test_writeln(self):
     doc = ReSTDocument()
     doc.writeln('foo')
     self.assertEqual(doc.getvalue(), six.b('foo\n'))
Example #18
0
 def test_codeblock(self):
     style = ReSTStyle(ReSTDocument())
     style.codeblock('foobar')
     self.assertEqual(style.doc.getvalue(), six.b('::\n\n  foobar\n\n\n'))
Example #19
0
 def test_sphinx_py_method(self):
     style = ReSTStyle(ReSTDocument())
     style.start_sphinx_py_method('method')
     style.end_sphinx_py_method()
     self.assertEqual(style.doc.getvalue(),
                      six.b('\n\n.. py:method:: method\n\n  \n\n'))
Example #20
0
 def test_handle_no_text_hrefs(self):
     style = ReSTStyle(ReSTDocument())
     style.start_a(attrs=[('href', 'http://example.org')])
     style.end_a()
     self.assertEqual(style.doc.getvalue(),
                      six.b('`<http://example.org>`_ '))
Example #21
0
 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(), six.b('foo\n'))
Example #22
0
 def test_writeln(self):
     doc = ReSTDocument()
     doc.writeln('foo')
     self.assertEqual(doc.getvalue(), six.b('foo\n'))
Example #23
0
 def test_italics(self):
     style = ReSTStyle(ReSTDocument())
     style.italics('foobar')
     self.assertEqual(style.doc.getvalue(), six.b('*foobar* '))
Example #24
0
 def test_bold(self):
     style = ReSTStyle(ReSTDocument())
     style.bold('foobar')
     self.assertEqual(style.doc.getvalue(), six.b('**foobar** '))
Example #25
0
 def test_table_of_contents(self):
     style = ReSTStyle(ReSTDocument())
     style.table_of_contents()
     self.assertEqual(style.doc.getvalue(), six.b('.. contents:: '))
Example #26
0
 def test_table_of_contents_with_title_and_depth(self):
     style = ReSTStyle(ReSTDocument())
     style.table_of_contents(title='Foo', depth=2)
     self.assertEqual(style.doc.getvalue(),
                      six.b('.. contents:: Foo\n   :depth: 2\n'))
Example #27
0
 def test_sphinx_reference_label_non_html_no_text(self):
     style = ReSTStyle(ReSTDocument())
     style.doc.target = 'man'
     style.sphinx_reference_label('foo')
     self.assertEqual(style.doc.getvalue(), six.b('foo'))
Example #28
0
 def test_sphinx_py_class(self):
     style = ReSTStyle(ReSTDocument())
     style.start_sphinx_py_class('FooClass')
     style.end_sphinx_py_class()
     self.assertEqual(style.doc.getvalue(),
                      six.b('\n\n.. py:class:: FooClass\n\n  \n\n'))
Example #29
0
 def test_include_doc_string(self):
     doc = ReSTDocument()
     doc.include_doc_string('<p>this is a <code>test</code></p>')
     self.assertEqual(doc.getvalue(), six.b('\n\nthis is a ``test`` \n\n'))
Example #30
0
 def test_h3(self):
     style = ReSTStyle(ReSTDocument())
     style.h3('foobar fiebaz')
     self.assertEqual(
         style.doc.getvalue(),
         six.b('\n\n-------------\nfoobar fiebaz\n-------------\n\n'))
Example #31
0
 def test_code(self):
     style = ReSTStyle(ReSTDocument())
     style.code('foobar')
     self.assertEqual(style.doc.getvalue(), six.b('``foobar`` '))
Example #32
0
 def test_ref(self):
     style = ReSTStyle(ReSTDocument())
     style.ref('foobar', 'http://foo.bar.com')
     self.assertEqual(style.doc.getvalue(),
                      six.b(':doc:`foobar <http://foo.bar.com>`'))