-
-
Save benman1/e2e507f61856b96217f611f8c22bb474 to your computer and use it in GitHub Desktop.
| """ | |
| 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 | |
| ) |
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.
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_repois 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 .
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.
I've been trying to debug this as I have been tasked to write something similar, and I can't get pass the code in line 28. It does not recognize "allsubmodules" as an argument of html. Any thoughts?
I have something that generates documentation for various levels of packages, however it lacks an index and links for the rest of modules. Any ideas?