Module clamming

Class ClamsModules

Description

Create documentation of a list of modules into Markdown or HTML.

Example

 >>> clams = ClamsModules(clamming)
 >>> md = clams.markdown()

Constructor

Create documentation from the given package name.

Parameters

modules: list(modules) A list of Python modules

Raises

TypeError: a given entry is not a module

View Source

def __init__(self, modules: list):
    """Create documentation from the given package name.

    :param modules: list(modules) A list of Python modules
    :raises: TypeError: a given entry is not a module

    """
    if isinstance(modules, list) is False:
        raise TypeError('Expected a list of Python modules. Got {:s} instead.'.format(str(modules)))
    self.__clams_packs = list()
    for m in modules:
        self.__clams_packs.append(ClamsPack(m))

Public functions

markdown_export_packages

Create a Markdown file for each of the packages.

Parameters

path_name: (str) Path where to add the exported md files
exporter: (HTMLDocExport) Options for HTML output files

Returns

(list) Exported file names

View Source

def markdown_export_packages(self, path_name: str, exporter: ExportOptions) -> list[str]:
    """Create a Markdown file for each of the packages.

        :param path_name: (str) Path where to add the exported md files
        :param exporter: (HTMLDocExport) Options for HTML output files
        :return: (list) Exported file names

        """
    out = list()
    for clams_pack in self.__clams_packs:
        out_md = os.path.join(path_name, clams_pack.name + '.md')
        if os.path.exists(path_name) is False:
            os.mkdir(path_name)
        logging.info('Export {:s}'.format(out_md))
        with codecs.open(out_md, 'w', 'utf-8') as fp:
            fp.write(clams_pack.markdown())
        out.append(out_md)
    return out

html_export_index

Write the index.html file from the list of packages.

Parameters

path_name: (str) Path where to add the exported index.html file
exporter: (HTMLDocExport) Options for HTML output files
readme: (str) A markdown README filename to be added into the index.html

Returns

(str) Filename of the created HTML index file

View Source

def html_export_index(self, path_name: str, exporter: ExportOptions, readme: str | None=None) -> str:
    """Write the index.html file from the list of packages.

        :param path_name: (str) Path where to add the exported index.html file
        :param exporter: (HTMLDocExport) Options for HTML output files
        :param readme: (str) A markdown README filename to be added into the index.html
        :return: (str) Filename of the created HTML index file

        """
    out = os.path.join(path_name, 'index.html')
    if os.path.exists(path_name) is False:
        os.mkdir(path_name)
    with codecs.open(out, 'w', 'utf-8') as fp:
        fp.write('<!DOCTYPE html>\n')
        fp.write('<html>\n')
        fp.write(exporter.get_head())
        fp.write('<body class="{:s}">\n'.format(exporter.get_theme()))
        fp.write('    {:s}\n'.format(exporter.get_header()))
        fp.write('    {:s}\n'.format(exporter.get_nav()))
        fp.write('    <main id="main-content">\n')
        if readme is not None:
            try:
                with codecs.open(readme, 'r', 'utf-8') as readme_fp:
                    readme_content = readme_fp.read()
                    if len(readme_content) > 0:
                        fp.write('    <section id="readme">\n')
                        fp.write(ClamUtils().markdown_to_html(readme_content))
                        fp.write('    </section>\n')
            except Exception as e:
                logging.error(e)
        fp.write('<h1>List of packages:</h1>\n')
        for clams_pack in self.__clams_packs:
            fp.write('      <h2>{:s}</h2>\n'.format(clams_pack.name))
            fp.write("      <p><a href='{:s}'>Get documentation</a></p>\n".format(clams_pack.name + '.html'))
        fp.write('    </main>\n')
        fp.write('    {:s}\n'.format(exporter.get_footer()))
        fp.write('</body>\n')
        fp.write('</html>\n')
    return out

html_export_packages

Create all the HTML files from the list of packages.

create the HTML file for each class of each given module;
create an index.html file.

Parameters

path_name: (str) Path where to add the exported index.html file
exporter: (HTMLDocExport) Options for HTML output files
readme: (str) A markdown README filename to be added into the index.html

Returns

(list) Exported file names

View Source

def html_export_packages(self, path_name: str, exporter: ExportOptions, readme: str | None=None) -> list:
    """Create all the HTML files from the list of packages.

        - create the HTML file for each class of each given module;
        - create an index.html file.

        :param path_name: (str) Path where to add the exported index.html file
        :param exporter: (HTMLDocExport) Options for HTML output files
        :param readme: (str) A markdown README filename to be added into the index.html
        :return: (list) Exported file names

        """
    out = list()
    out_index = self.html_export_index(path_name, exporter, readme)
    out.append(out_index)
    for i in range(len(self.__clams_packs)):
        clams_pack = self.__clams_packs[i]
        exporter.prev_module = None if i == 0 else self.__clams_packs[i - 1].name + '.html'
        exporter.next_module = None if i + 1 == len(self.__clams_packs) else self.__clams_packs[i + 1].name + '.html'
        out_html = clams_pack.html_export_clams(path_name, exporter)
        out.extend(out_html)
    return out