ClammingPy 1.8

https://sourceforge.net/projects/clamming/

Module clamming

Class ClamsClass

Description

Convert a parsed class object into Markdown or HTML content.

Example
 >>> clamming = ClammingClassParser(Vehicle)
 >>> clams = ClamsClass(clamming)
 >>> md = clams.markdown()

Constructor

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

Example
 >>> self.markdowner = markdown2.Markdown()
 >>> self.formatter = pygments_formatter.HtmlFormatter(**ClamsClass.HTML_FORMATTER_ARGS)
 >>> self.lexer = pygments_lexers.PythonLexer()
Parameters
  • parsed_obj: A parsed object.
View Source
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])

Public functions

get_name

Return the name of the documented class.

View Source
def get_name(self) -> str:
    """Return the name of the documented class."""
    return self.__info_class_name

markdown

Get Markdown content of the parsed object.

Returns
  • (str) Content in Markdown format
View Source
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)

html

Get HTML content of the parsed object.

Returns
  • (str) Content in HTML format
Raises
  • ImportError: if one of the requirements is not installed
View Source
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>', '')

Private functions

_source_accordion

Return the given content embedded into a details element.

Parameters
  • header_content: (str) Content of the collapsed part
  • main_content: (str) Content of the expanded part
Returns
  • (str) HTML-5 of an article
View Source
@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)

_docstring_article

Return the given content embedded into an article.

Parameters
  • content: Content of the article
Returns
  • (str) HTML-5 of an article
View Source
@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>', '')

Protected functions

__docstring_to_html

Return the HTML of the given docstring.

Parameters
  • docstring: (str)
Returns
  • (str) HTML
View Source
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)

__claminfo_to_html

Return the HTML of the given ClamInfo instance.

Returns
  • (str) HTML
Parameters
  • claminfo
  • with_name
View Source
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>', '')