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).

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
    )

Thanks for replying so quickly! The trouble is that I need something that works without having to turn to the command prompt. I want to create some code that does just that. My program can open a package and create documentation for its modules and the modules of subpackages. But it lacks links to the other modules in the form of an index. I'm quite lost.

I think, the standard output from pdoc --html your_repo is already quite good - I don't remember if this snippet serves any purpose beyond what you get out of the box from pdoc.

So, I've updated your code. I removed the markdown possibility and, now, the directory hierarchy is respected and the hyperlinks all work.

Cool, nice to hear! I might have a look later.

Cool, nice to hear! I might have a look later.

I believe I have forked it and revised it. I'm new to this, I'm unsure of what to do next,

It's simple - it's just a gist, not a repo. You don't need to do anything. People can find yours from the comment section or through the forks link. I can choose to update mine at some point (which I might, but not right now).

…

On Mon, 11 Jan 2021, 20:58 ghaleon7, ***@***.***> wrote: ***@***.**** commented on this gist. ------------------------------ Cool, nice to hear! I might have a look later. I believe I have forked it and revised it. I'm new to this, I'm unsure of what to do next, — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <https://gist.github.com/e2e507f61856b96217f611f8c22bb474#gistcomment-3590252>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACSJO7EWJZEIB3NGKG5Z6T3SZNRAXANCNFSM4VOP5WOQ> .

It's simple - it's just a gist, not a repo. You don't need to do anything. People can find yours from the comment section or through the forks link. I can choose to update mine at some point (which I might, but not right now).
…
On Mon, 11 Jan 2021, 20:58 ghaleon7, @.> wrote: @.* commented on this gist. ------------------------------ Cool, nice to hear! I might have a look later. I believe I have forked it and revised it. I'm new to this, I'm unsure of what to do next, — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://gist.github.com/e2e507f61856b96217f611f8c22bb474#gistcomment-3590252, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACSJO7EWJZEIB3NGKG5Z6T3SZNRAXANCNFSM4VOP5WOQ .

Good news, the code is updated. Now it uses recursion, so it's adaptable to any folder organization. I'll update my fork later on.