How do I resolve No Modules found matching spec when running pdoc (in Windows)?

Question

I'm trying to run the simple demo script from pdoc documentation in windows from the command line. Using python 3.11.4 with virtualenv and PYTHONPATH set to folder in question.

"""
A small `pdoc` example.
"""

class Dog:
    """ (dog) """
    name: str
    """The name of our dog."""
    friends: list["Dog"]
    """The friends of our dog."""

    def __init__(self, name: str):
        """Make a Dog without any friends (yet)."""
        self.name = name
        self.friends = []

    def bark(self, loud: bool = True):
        """*woof*"""

> pdoc .\demo.py

I get the following error message(s)

Warn: pdoc cannot load 'pdoc' because a module with the same name is already imported in pdoc's Python process. pdoc will document the loaded module from C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\__init__.py instead.
Warn: Cannot find spec for pdoc.demo (from .\demo.py):
Traceback (most recent call last):
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\extract.py", line 62, in walk_specs
    raise ModuleNotFoundError(modname)
ModuleNotFoundError: pdoc.demo
 (C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\web.py:105)
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Pythons\virtenvs\glogger11.4\Scripts\pdoc.exe\__main__.py", line 7, in <module>
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\__main__.py", line 207, in cli
    httpd = pdoc.web.DocServer((opts.host, opts.port or 8080), opts.modules)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\web.py", line 105, in __init__
    module_names = extract.walk_specs(specs)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc\extract.py", line 85, in walk_specs
    raise ValueError(
ValueError: No modules found matching spec: .\demo.py
(

Answer 1

Warn: pdoc cannot load 'pdoc' because a module with the same name is already imported in pdoc's Python process. pdoc will document the loaded module from C:\Pythons\virtenvs\glogger11.4\Lib\site-packages\pdoc_init_.py instead.

I think this error message gives it away. Are you running pdoc in a folder named pdoc, and do you also have an __init__.py in that folder? If there is an __init__.py file, pdoc will treat the current directory as a module.