benman1/create_package_doc.py

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

Please note that this script is currently limited to one level of submodules. Also it's a bit ugly. Help fix it, if you like.

This looks atrocious for markdown (my impresssion)
"""
from os import path, makedirs
import argparse
import pdoc


def make_pdoc(output_dir: str, module_name: str, html: bool=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)

    file_extension = 'html' if html else 'md'
    index = 'index' if html else 'Readme'
    mod = pdoc.import_module(module_name)
    doc = pdoc.Module(mod, allsubmodules=True)
    if html:
        string = doc.html(external_links=True)
    else:
        string = doc.text()

    # Package level
    ensure_dir(output_dir)
    with open(
            path.join(
                output_dir,
                f'{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()

        if submodule.is_package():
            ext = f'/{index}.{file_extension}'
        else:
            ext = f'.m.{file_extension}'
        dpath = path.join(
            output_dir,
            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()

                if subsubmodule.is_package():
                    ext = f'.{file_extension}'
                else:
                    ext = f'.m.{file_extension}'
                with open(
                        path.join(
                            output_dir,
                            '.'.join(subsubmodule.name.split('.')[1:]) + 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
    )
	"""
	Adapter from
	[stackoverflow](https://stackoverflow.com/questions/39453948/create-a-html-page-with-a-list-of-packages-using-pdoc-module).

	Please note that this script is currently limited to one level of submodules. Also it's a bit ugly. Help fix it, if you like.

	This looks atrocious for markdown (my impresssion)
	"""
	from os import path, makedirs
	import argparse
	import pdoc


	def make_pdoc(output_dir: str, module_name: str, html: bool=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)

	file_extension = 'html' if html else 'md'
	index = 'index' if html else 'Readme'
	mod = pdoc.import_module(module_name)
	doc = pdoc.Module(mod, allsubmodules=True)
	if html:
	string = doc.html(external_links=True)
	else:
	string = doc.text()

	# Package level
	ensure_dir(output_dir)
	with open(
	path.join(
	output_dir,
	f'{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()

	if submodule.is_package():
	ext = f'/{index}.{file_extension}'
	else:
	ext = f'.m.{file_extension}'
	dpath = path.join(
	output_dir,
	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()

	if subsubmodule.is_package():
	ext = f'.{file_extension}'
	else:
	ext = f'.m.{file_extension}'
	with open(
	path.join(
	output_dir,
	'.'.join(subsubmodule.name.split('.')[1:]) + 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
	)