Impossible to import module in current working directory

[tlescoat]

It is currently impossible to document a module locally defined. It makes working with pdoc painful. Given the following folder structure:

some/random/folder/
    mymodule/
        __init__.py
        subA.py
        subB.py

The following doesn't work:

> cd some/random/folder
> pdoc --html --html-dir doc mymodule

pdoc will only find __init__.py, however since the current working directory is not in sys.path python will not import the whole module. It won't even generate documentation for variables / functions in __init__.py...

The fix is simple, add these two lines to pdoc:405:

sys.path.insert(0, os.getcwd())
pdoc.import_path.insert(0, os.getcwd())

Then you can now work in any directory

[BurntSushi]

Have you tried setting the PYTHONPATH variable? Modifying sys.path is generally not advisable.

For what it's worth, it looks like you're frustrated by Python's module import semantics rather than pdoc's behavior.

[tlescoat]

Thanks for your quick answer !

Yes, I tried in a vm, but in general I find using pythonpath highly inconvenient. Also, the point of this tool is to be lightweight (as I understood) and requiring users to make a virtualenv / modifying an environment variable kinda defeats this objective.

Also, on a security side, this change of sys.path and/or PYTHONPATH are the same

[BurntSushi]

but in general I find using pythonpath highly inconvenient

All you need to do: PYTHONPATH=. pdoc ....

Also, the point of this tool is to be lightweight (as I understood) and requiring users to make a virtualenv / modifying an environment variable kinda defeats this objective.

I disagree. Requiring users to develop code idiomatically (i.e., virtualenv) or using already established mechanisms for hacking the import paths (e.g., setting PYTHONPATH) is precisely what makes pdoc lightweight. Adding hacks to accommodate non-standard or legacy environments is exactly what leads to bloat.

I won't accept a patch that modifies sys.path without stronger justification. Sorry.

[BurntSushi]

Additionally, modifying sys.path is implicit, whereas using PYTHONPATH is explicit. Subtly changing how modules are normally imported makes debugging harder.