Create a documentation for a complete python package using pdoc

create_package_doc.py

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

"""
Creates documentation for a package using pdoc
"""
import os
from os import path, makedirs
import argparse
import pdoc

def ensure_dir(dpath: str):
    if not path.exists(dpath):
        makedirs(dpath)

def make_pdoc(output_dir: str, module_name: str):
    """Create a doumentation for the whole package.
    Parameters:
    -----------
     - output_dir - str, the folder where the project folder documentation will be exported
     - module_name - str, name of the package
    Output:
    -----------
     - folder with documentation
    """
    file_extension = 'html'
    index = 'index'
    mod = pdoc.import_module(module_name)
    doc = pdoc.Module(mod)
    string = doc.html(external_links=True)
    
    # Package level
    # Documentation folder
    proj_path = path.join(output_dir, doc.name)
    # Ensures the documentation folder exists
    ensure_dir(proj_path)
    filename = path.join(proj_path,f'{index}.{file_extension}')
    # Creates an index
    with open(filename, 'w') as html_file:
        html_file.write(string)

    # Sublevel 1
    if bool(doc.submodules()):
        for submodule in doc.submodules():
            # Creates the submodule path 
            proj_path = path.join(
                    output_dir,
                    doc.name.split('.')[-1],
                    submodule.name.split('.')[-1])
            print(f'Creating documentation for {submodule.name}')
            string = submodule.html(external_links=True)
            if submodule.is_package:
                ensure_dir(proj_path)
                ext = f'\{index}.{file_extension}'
            else:
                ext = f'.{file_extension}'
            with open(proj_path + ext, 'w') as html_file:
                html_file.write(string)
            # Sublevel 2
            if bool(submodule.submodules()):
                for subsubmodule in submodule.submodules():
		    # Creates the subsubmodule path 
                    proj_path = path.join(
                            output_dir, 
                            doc.name.split('.')[-1], 
                            submodule.name.split('.')[-1],
                            subsubmodule.name.split('.')[-1])
                    print(f'Creating documentation for {subsubmodule.name}')
                    string = subsubmodule.html(external_links=True)
                    if subsubmodule.is_package:
                        ensure_dir(proj_path)
                        ext = f'\{index}.{file_extension}'
                    else:
                        ext = f'.{file_extension}'
                    with open(proj_path + ext,'w') as html_file:
                        html_file.write(string)

if __name__ == '__main__':
    parser = argparse.ArgumentParser('Create package doc')
    parser.add_argument(
        'module',
        help='the name of the module'
    )
    parser.add_argument(
        '--output_dir',
        dest='output_dir',
        default='docs',
        help='the output directory of the documentation',
    )
    parser.add_argument(
        '--text',
        dest='html',
        action='store_const',
        const=False,
        default=True,
        help='Whether to create markdown documentation (default: html)'
    )
    args = parser.parse_args()
    make_pdoc(
        module_name=args.module,
        output_dir=args.output_dir,
        html=args.html
    )