Convert a parsed class object into Markdown or HTML content.
Example
>>> clamming = ClammingClassParser(Vehicle)
>>> clams = ClamsClass(clamming)
>>> md = clams.markdown()
Convert a parsed class object into Markdown or HTML content.
>>> clamming = ClammingClassParser(Vehicle)
>>> clams = ClamsClass(clamming)
>>> md = clams.markdown()
Create documentation from the given parsed class object.
HTML conversion depends on external libraries. It could be disabled if any of them is missing. If not, customizing the HTML export can be done by assigning different values to members or by changing their optional parameters.
See Pygments
documentation:
HtmlFormatter
and
Lexer
>>> self.markdowner = markdown2.Markdown()
>>> self.formatter = pygments_formatter.HtmlFormatter(**ClamsClass.HTML_FORMATTER_ARGS)
>>> self.lexer = pygments_lexers.PythonLexer()
def __init__(self, parsed_obj: ClammingClassParser):
"""Create documentation from the given parsed class object.
HTML conversion depends on external libraries. It could be disabled
if any of them is missing. If not, customizing the HTML export can
be done by assigning different values to members or by changing their
optional parameters.
See `Pygments` documentation:
[HtmlFormatter](https://pygments.org/docs/formatters/#HtmlFormatter)
and
[Lexer](https://pygments.org/docs/lexers/#pygments.lexers.python.PythonLexer)
:example:
>>> self.markdowner = markdown2.Markdown()
>>> self.formatter = pygments_formatter.HtmlFormatter(**ClamsClass.HTML_FORMATTER_ARGS)
>>> self.lexer = pygments_lexers.PythonLexer()
:param parsed_obj: A parsed object.
"""
self.__utils = ClamUtils()
self.__info_class_name = parsed_obj.get_obj_clams().name
self.__info_class_description = parsed_obj.get_obj_clams()
self.__info_constructor = parsed_obj.init_clams
self.__info_public_fcts = list()
for fct_name in parsed_obj.fct_clams:
if fct_name.startswith('_') is False:
self.__info_public_fcts.append(parsed_obj.fct_clams[fct_name])
self.__info_private_fcts = list()
for fct_name in parsed_obj.fct_clams:
if fct_name.startswith('_') is True and fct_name.startswith('__') is False:
self.__info_private_fcts.append(parsed_obj.fct_clams[fct_name])
self.__info_protected_fcts = list()
for fct_name in parsed_obj.fct_clams:
if fct_name.startswith('__') is True and fct_name.endswith('__') is False:
self.__info_protected_fcts.append(parsed_obj.fct_clams[fct_name])
self.__info_overloads = list()
for fct_name in parsed_obj.fct_clams:
if fct_name.startswith('__') is True and fct_name.endswith('__') is True:
self.__info_overloads.append(parsed_obj.fct_clams[fct_name])
Return the name of the documented class.
def get_name(self) -> str:
"""Return the name of the documented class."""
return self.__info_class_name
Get Markdown content of the parsed object.
def markdown(self) -> str:
"""Get Markdown content of the parsed object.
:return: (str) Content in Markdown format
"""
md = list()
md.append('## Class `{:s}`\n'.format(self.__info_class_name))
if self.__info_class_description.docstring is not None:
md.append('### Description\n')
md.append(ClamInfoMarkdown.convert_docstring(self.__info_class_description.docstring))
md.append('\n')
if len(self.__info_constructor.name) > 0:
md.append('### Constructor\n')
md.append(str(ClamInfoMarkdown(self.__info_constructor)))
md.append('\n')
if len(self.__info_public_fcts) > 0:
md.append('### Public functions\n')
for info in self.__info_public_fcts:
md.append(str(ClamInfoMarkdown(info)))
md.append('\n')
if len(self.__info_private_fcts) > 0:
md.append('### Private functions\n')
for info in self.__info_private_fcts:
md.append(str(ClamInfoMarkdown(info)))
md.append('\n')
if len(self.__info_protected_fcts) > 0:
md.append('### Protected functions\n')
for info in self.__info_protected_fcts:
md.append(str(ClamInfoMarkdown(info)))
md.append('\n')
if len(self.__info_overloads) > 0:
md.append('### Overloads\n')
for info in self.__info_overloads:
md.append(str(ClamInfoMarkdown(info)))
md.append('\n')
return '\n'.join(md)
Get HTML content of the parsed object.
def html(self) -> str:
"""Get HTML content of the parsed object.
:return: (str) Content in HTML format
:raises: ImportError: if one of the requirements is not installed
"""
if self.__utils.markdowner is None:
logging.warning('Markdown to HTML conversion is disabled.')
return ''
hd = list()
cid = self.__info_class_name
hd.append('<section id="#{:s}">'.format(cid))
hd.append('<h2>Class {:s}</h2>\n'.format(self.__info_class_name))
if self.__info_class_description.docstring is not None:
hd.append('<section>')
hd.append('<h3 id="#description_{:s}">Description</h3>'.format(cid))
_html = self.__docstring_to_html(self.__info_class_description.docstring)
hd.append(ClamsClass._docstring_article(_html))
hd.append('</section>')
if len(self.__info_constructor.name) > 0:
hd.append('<section>')
hd.append('<h3 id="#constructor_{:s}">Constructor</h3>'.format(cid))
_html = self.__claminfo_to_html(self.__info_constructor, with_name=False)
hd.append(_html)
hd.append('</section>')
if len(self.__info_public_fcts) > 0:
hd.append('<section>')
hd.append('<h3 id="#public_fct_{:s}">Public functions</h3>'.format(cid))
for info in self.__info_public_fcts:
hd.append(self.__claminfo_to_html(info))
hd.append('</section>')
if len(self.__info_private_fcts) > 0:
hd.append('<section>')
hd.append('<h3 id="#private_fct_{:s}">Private functions</h3>'.format(cid))
for info in self.__info_private_fcts:
hd.append(self.__claminfo_to_html(info))
hd.append('</section>')
if len(self.__info_protected_fcts) > 0:
hd.append('<section>')
hd.append('<h3 id="#protected_fct_{:s}">Protected functions</h3>'.format(cid))
for info in self.__info_protected_fcts:
hd.append(self.__claminfo_to_html(info))
hd.append('</section>')
if len(self.__info_overloads) > 0:
hd.append('<section>')
hd.append('<h3 id="#overloads_{:s}">Overloads</h3>'.format(cid))
for info in self.__info_overloads:
hd.append(self.__claminfo_to_html(info))
hd.append('</section>')
hd.append('</section>')
html_result = '\n'.join(hd)
return html_result.replace('<p></p>', '')
Return the given content embedded into a details element.
@staticmethod
def _source_accordion(header_content: str, main_content: str) -> str:
"""Return the given content embedded into a details element.
:param header_content: (str) Content of the collapsed part
:param main_content: (str) Content of the expanded part
:return: (str) HTML-5 of an article
"""
h = list()
h.append(' <details>')
h.append(' <summary>')
h.append(header_content)
h.append(' </summary>')
h.append(main_content)
h.append(' </details>')
return '\n'.join(h)
Return the given content embedded into an article.
@staticmethod
def _docstring_article(content: str) -> str:
"""Return the given content embedded into an article.
:param content: Content of the article
:return: (str) HTML-5 of an article
"""
h = list()
h.append(' <article class="docstring">')
h.append(content)
h.append(' </article>')
html_result = '\n'.join(h)
return html_result.replace('<p></p>', '')
Return the HTML of the given docstring.
def __docstring_to_html(self, docstring: str) -> str:
"""Return the HTML of the given docstring.
:param docstring: (str)
:return: (str) HTML
"""
_md = ClamInfoMarkdown.convert_docstring(docstring)
return self.__utils.markdown_to_html(_md)
Return the HTML of the given ClamInfo instance.
def __claminfo_to_html(self, claminfo: ClamInfo, with_name=True) -> str:
"""Return the HTML of the given ClamInfo instance.
:return: (str) HTML
"""
h = list()
if with_name is True:
h.append('<h4>{:s}</h4>\n'.format(claminfo.name))
params = [p for p in claminfo.args]
if 'self' in params:
params.remove('self')
if claminfo.docstring is not None:
_html = self.__docstring_to_html(claminfo.docstring)
if len(params) > 0 and '<h5>Parameters</h5>' not in _html:
_md = '\n\n##### Parameters\n'
_md += '\n'.join(['- **{:s}**'.format(p) for p in params])
_html += self.__utils.markdown_convert(_md)
h.append(ClamsClass._docstring_article(_html))
h.append('\n')
if len(claminfo.source) > 0:
_html = ClamUtils().source_to_html(claminfo.source)
h.append(ClamsClass._source_accordion('View Source', _html))
h.append('\n')
html_result = '\n'.join(h)
return html_result.replace('<p></p>', '')