Exhale Parse Module

exhale.parse.walk(textRoot, currentTag, level, prefix=None, postfix=None, unwrapUntilPara=False)[source]

Note

This method does not cover all possible input doxygen types! This means that when an unsupported / unrecognized doxygen tag appears in the xml listing, the raw xml will appear on the file page being documented. This traverser is greedily designed to work for what testing revealed as the bare minimum required. Please see the Doxygen ALIASES section for how to bypass invalid documentation coming form Exhale.

Recursive traverser method to parse the input parsed xml tree and convert the nodes into raw reStructuredText from the input doxygen format. Not all doxygen markup types are handled. The current supported doxygen xml markup tags are:

  • para

  • orderedlist

  • itemizedlist

  • verbatim (specifically: embed:rst:leading-asterisk)

  • formula

  • ref

  • emphasis (e.g., using em)

  • computeroutput (e.g., using c)

  • bold (e.g., using b)

The goal of this method is to “explode” input xml data into raw reStructuredText to put at the top of the file pages. Wielding beautiful soup, this essentially means that you need to expand every non para tag into a para. So if an ordered list appears in the xml, then the raw listing must be built up from the child nodes. After this is finished, though, the bs4.BeautifulSoup.get_text() method will happily remove all remaining para tags to produce the final reStructuredText provided that the original “exploded” tags (such as the ordered list definition and its listitem children) have been removed from the soup.

Parameters
textRoot (ExhaleRoot)

The text root object that is calling this method. This parameter is necessary in order to retrieve / convert the doxygen \ref SomeClass tag and link it to the appropriate node page. The textRoot object is not modified by executing this method.

currentTag (bs4.element.Tag)

The current xml tag being processed, either to have its contents directly modified or unraveled.

level (int)

Warning

This variable does not represent “recursion depth” (as one would typically see with a variable like this)!

The block level of indentation currently being parsed. Because we are parsing a tree in order to generate raw reStructuredText code, we need to maintain a notion of “block level”. This means tracking when there are nested structures such as a list within a list:

1. This is an outer ordered list.

    - There is a nested unordered list.
    - It is a child of the outer list.

2. This is another item in the outer list.

The outer ordered (numbers 1 and 2) list is at indentation level 0, and the inner unordered (-) list is at indentation level 1. Meaning that level is used as

indent = "    " * level
# ... later ...
some_text = "\n{indent}{text}".format(indent=indent, text=some_text)

to indent the ordered / unordered lists accordingly.

exhale.parse.convertDescriptionToRST(textRoot, node, soupTag, heading)[source]

Parses the node XML document and returns a reStructuredText formatted string. Helper method for getBriefAndDetailedRST().

Todo

actually document this

exhale.parse.getBriefAndDetailedRST(textRoot, node)[source]

Given an input node, return a tuple of strings where the first element of the return is the brief description and the second is the detailed description.

Todo

actually document this