Can pdoc be further automated?

[johnrdirk]

First I want to say: I love pdoc ❤️, thank you so much for this project 🙏. What I love is:

• quality of docs reflects quality of my code: if my code sucks then so will my docs, hence I'm not trying to create docs to compensate for poor code. It forces me to code as per best practices (typing, docstrings, tests...)
• little overhead: I don't have to maintain separate documentation, my code is my docs

🤔 Problem Description

Maybe I'm doing something wrong, but I find myself having to do repetitive work such as:

• create init.py files otherwise pdoc won't parse a folder (and I have to do this recursively in all subfolders)
• add .. include:: ./README.md to init.py: README.md are the only markdown files I allow myself to create, they are present at the root of subfolders/models to give a short intro, again not something I do for pdoc, something I've been doing as part of my code for years

❓ Question

Is it possible (either via CLI or programmatically) to configure pdoc to perform the below tasks?

• automatically generate doc for a folder and all its subfolders without having to create __init__.py files
• other tasks such as adding .. include:: ./README.md to init.py` are also done automatically without being explicitly defined

I'm asking the question to check if that's in the "spirit" of pdoc or whether I should seek another framework

⭐ End-goal

For me in an ideal world I would do 2 things:

• Create/document my code as per best practices without caring for documentation (the README.md as module intro being the only exception)
• Run pdoc over my code and I have my docs

[johnrdirk]

It seems to be in the "spirit" of pdoc to make dynamic changes for doc generation purposes:

• https://pdoc.dev/docs/pdoc.html#using-pdoc-as-a-library: "Using pdoc as a library [...] This makes it possible to do custom adjustments to your Python code before pdoc is used"
• https://github.com/mitmproxy/pdoc/blob/main/examples/library-usage/make.py

[mhils]

Thank you, appreciate it! :)

automatically generate doc for a folder and all its subfolders without having to create init.py files

Does pdoc **/*.py work maybe? Practically speaking I think you should consider adding __init__.py files anyhow. See
https://docs.python.org/3/tutorial/modules.html#packages and https://stackoverflow.com/questions/37139786/is-init-py-not-required-for-packages-in-python-3-3.

other tasks such as adding .. include:: ./README.md to init.py` are also done automatically without being explicitly defined

As you mentioned in #690 (comment), I think that's a prime use case for using pdoc as a library. I'd like to avoid such "magic" in pdoc itself. :)

[johnrdirk]

Hey @mhils thanks for feedback. I think I'll end up going for a code (not tested yet) along the lines of below snippet:

• backfill of required init.py / includes etc.. outside pdoc.: e.g. automatically add to __init__.py files if they are missing, again so we improve our code because it needs to be, not just to please pdoc
• call pdoc on whatever there is: without changing the logic of pdoc itself

import pdoc

SRC = "src"
DST = "docs"
MODULES = []

# For each folder (recursive) in source code:
for dirpath, dirnames, filenames in os.walk(SRC):
    init_path = os.path.join(dirpath, '__init__.py')
    readme_path = os.path.join(dirpath, 'README.md')

    # Create __init__.py if missing
    if not os.path.exists(init_path):
        open(init_path, 'a').close()

    # Check presence of README.md
    if 'README.md' in filenames:
        with open(init_path, 'r+') as init_file:
            content = init_file.read()
            include_directive = '"""\n.. include:: ../README.md\n"""'

	   # Update init with include if necessary
            if include_directive not in content:
                init_file.seek(0, 0)
                init_file.write(include_directive + content)
		# Adding folder to list of modules
		MODULES += [dirpath]
		
pdoc.pdoc(MODULES,output_directory=DST)