Create a documentation for a complete python package

create_package_doc.py

"""
Adapter from
[stackoverflow](https://stackoverflow.com/questions/39453948/create-a-html-page-with-a-list-of-packages-using-pdoc-module).

It's a bit ugly. Help fix it, if you like.
"""
from os import path, makedirs
import pdoc


def make_pdoc(html=True):
    """Create a doumentation for the whole package.

    Parameters:
    -----------
    html - (bool) if true generate html output to .html files;
        if false, generate markdown (text) output to .md files.
    """
    def ensure_dir(dpath: str):
        if not path.exists(dpath):
            makedirs(dpath)

    # pdoc.import_path.append(libpath)  
    file_extension = 'html' if html else '.md'
    mod = pdoc.import_module('generic_model')
    doc = pdoc.Module(mod, allsubmodules=True)
    if html:
        string = doc.html(external_links=True)
    else:
        string = doc.text()

    # Package level
    ensure_dir('docs/')
    with open(f'docs/index.{file_extension}', 'w') as html_file:
        html_file.write(string)

    # Sublevel 1
    for submodule in doc.submodules():
        if html:
            string = submodule.html(external_links=True)
        else:
            string = submodule.text(external_links=True)

        if submodule.is_package():
            ext = f'/index.{file_extension}'
        else:
            ext = f'.m.{file_extension}'
        dpath = 'docs/' + submodule.name.split('.')[-1]
        ensure_dir(dpath)
        with open(dpath + ext, 'w') as html_file:
            html_file.write(string)
        # Sublevel 2
        if submodule.submodules():
            for subsubmodule in submodule.submodules():
                print(f'Creating documentation for {subsubmodule.name}')
                if html:
                    string = subsubmodule.html(external_links=True)
                else:
                    string = subsubmodule.text(external_links=True)

                if subsubmodule.is_package():
                    ext = f'.{file_extension}'
                else:
                    ext = f'.m.{file_extension}'
                with open(
                        'docs/'
                        + '.'.join(subsubmodule.name.split('.')[1:])
                        + ext,
                        'w'
                ) as html_file:
                    html_file.write(string)


if __name__ == '__main__':
    make_pdoc()