2

pdoc3 is a nice tool to generate documentation from code. In one of my projects, I got some exception. Wonder if it is caused by project structure. These are the folder structure of my two projects.

proj_A
  -src
    -automation
      -hl7ctl
        (has a definition of HL7CtlClient)

proj_B
  -src
    -automation
      -connctl
        -core.py
        -utility.py (uses HL7CtlClient)

In the utility.py of the proj_B, I have to import a class from project_A

from automation.hl7ctl import HL7CtlClient

This causes the following error by running pdoc3 at src folder in proj_B. The proj_A has been installed by using 'sudo pip3 install proje_A.gz'

automation.connctl.core No module named 'automation.hl7ctl' in pdoc3's code:

(See https://github.com/pdoc3/pdoc/blob/master/pdoc/init.py#L519)

Traceback (most recent call last):
  File "/usr/local/bin/pdoc3", line 11, in <module>
    load_entry_point('pdoc3==0.5.5.dev13+g43f28dd.d20190427', 'console_scripts', 'pdoc3')()
  File "/usr/local/lib/python3.6/dist-packages/pdoc3-0.5.5.dev13+g43f28dd.d20190427-py3.6.egg/pdoc/cli.py", line 419, in main
    for module in args.modules]
  File "/usr/local/lib/python3.6/dist-packages/pdoc3-0.5.5.dev13+g43f28dd.d20190427-py3.6.egg/pdoc/cli.py", line 419, in <listcomp>
    for module in args.modules]
  File "/usr/local/lib/python3.6/dist-packages/pdoc3-0.5.5.dev13+g43f28dd.d20190427-py3.6.egg/pdoc/__init__.py", line 943, in __init__
    m, docfilter=docfilter, supermodule=self, context=self._context)
  File "/usr/local/lib/python3.6/dist-packages/pdoc3-0.5.5.dev13+g43f28dd.d20190427-py3.6.egg/pdoc/__init__.py", line 943, in __init__
    m, docfilter=docfilter, supermodule=self, context=self._context)
  File "/usr/local/lib/python3.6/dist-packages/pdoc3-0.5.5.dev13+g43f28dd.d20190427-py3.6.egg/pdoc/__init__.py", line 940, in __init__
    m = import_module(fullname)
  File "/usr/local/lib/python3.6/dist-packages/pdoc3-0.5.5.dev13+g43f28dd.d20190427-py3.6.egg/pdoc/__init__.py", line 520, in import_module
    raise ValueError('File or module {!r} not found'.format(module))
ValueError: File or module 'automation.connctl.core' not found

This is how I run pdoc3:

cd src
pdoc3 --overwrite --html --html-dir ../docs/APIs --template-dir ../docs/templates automation

There are __init__.py in automation and its subfolders but not 'src'.

The automation/__init__.py has the following content:

__import__("pkg_resources").declare_namespace(__name__)
thsieh
  • 620
  • 8
  • 24
  • How do you run pdoc, `pdoc3 --html project_B/src`? Is _project\_*/src/automation_ a [namespace package](https://packaging.python.org/guides/packaging-namespace-packages/) without _\_\_init\_\_.py_? – K3---rnc Apr 28 '19 at 12:00
  • Thanks for helping. I have updated the question. So once I run it as you just suggested, it failed at parsing the `__init__.py` in the automation folder. After I removed all the content of the `__init.py__`, it builds successfully. I wonder why. The '__import__("pkg_resources").declare_namespace(__name__)' is an inheirted code. – thsieh Apr 29 '19 at 01:22
  • Would you be willing to construct a [MWE](https://en.wikipedia.org/wiki/Minimal_Working_Example) zip archive and post it on [GitHub](https://github.com/pdoc3/pdoc) as a new issue? The module importation system, particularly as far as namespace packages go, needs a slight revamp. – K3---rnc Apr 30 '19 at 19:08
  • Thanks K3. I restructure my package so to use the implicit namespace of the PEP-420 https://www.python.org/dev/peps/pep-0420/. Now there is no problem. Mixing implicit namespace and some older way might be the reason why it didn't work. The pdoc3 does what it supposes to do. Thanks again! – thsieh May 01 '19 at 05:27
  • Welcome to test namespace package importing improvements in https://github.com/pdoc3/pdoc/pull/62. This should land in v0.6.0 shortly. – K3---rnc May 03 '19 at 03:34

1 Answers1

2

pydoc and pdoc read your code!!!

if you will run it from the same directory pdoc --html . or pydoc -w . it should work if all the modules are in the same directory. but if they are not:

make sure your modules in each directory has it sys full path appendded.

sys.path.append("D:/Coding/project/...the path the model is in")

Or, even better, you can make python to get the path:

path = os.path.dirname(os.path.abspath(__file__))
sys.path.append(path)

Relative path will not do the trick!

Gilco
  • 1,326
  • 12
  • 13