pythonpython-sphinxdocutils

Parse raw rst string using nested_parse


I'm writing a sphinx extension that transforms a custom directive into a flat-table.

From inside the .run(self) method, I build a complete flat-table declaration in pure .rst, and I'd like to feed that string into the internal parser, so it is transformed into a Node, which I'll return from .run(self).

I believe nested_parse is the right method to use. It is normally used to parse nested content from a directive, but I suppose it can be used with any array of strings that is valid .RST

 def run(self):
        decl = '''
.. flat-table:: Characteristics of the BLE badge
    :header-rows: 1

    * - Service
      - Characteristic
      - Properties
    * - :rspan:`2` 0xfee7
      - 0xfec7
      - WRITE
    * - 0xfec8
      - INDICATE
    * - 0xfec9
      - READ
    * - 0xfee0
      - 0xfee1


        '''

        table_node = nodes.paragraph()
        self.state.nested_parse(decl.split('\n'), 0, table_node)
        
        return [table_node]

However, this fails :

Exception occurred:
  File "C:\Users\200207121\AppData\Roaming\Python\Python38\site-packages\docutils\parsers\rst\states.py", line 287, in nested_parse
    if block.parent and (len(block) - block_length) != 0:
AttributeError: 'list' object has no attribute 'parent'

What should I do to parse raw .rst text using nested_parse ?


Solution

  • nested_parse expects the content to be a StringList.

    from docutils.statemachine import StringList
    self.state.nested_parse(StringList(decl.split('\n')), 0, table_node)