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 nonpara
tag into apara
. 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, thebs4.BeautifulSoup.get_text()
method will happily remove all remainingpara
tags to produce the final reStructuredText provided that the original “exploded” tags (such as the ordered list definition and itslistitem
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. ThetextRoot
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
and2
) list is at indentation level0
, and the inner unordered (-
) list is at indentation level1
. Meaning that level is used asindent = " " * 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 forgetBriefAndDetailedRST()
.Todo
actually document this