pdoc3 / pdoc3/pdoc

Non-Python Type for pybind11 Module

Open
#237 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Python
Stars
1.2k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

Expected Behavior

When I try to document my codebase which contains a pybind11 module, pdoc seems to be trying to generate python code with a c++ function signature leading to the error "Name 'at' is not defined". The full error is

Traceback (most recent call last):
  File "/home/max/code/torchjpeg/.venv/bin/pdoc", line 11, in <module>
    load_entry_point('pdoc3==0.8.4', 'console_scripts', 'pdoc')()
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/cli.py", line 501, in main
    recursive_write_files(module, ext='.html', **template_config)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/cli.py", line 340, in recursive_write_files
    recursive_write_files(submodule, ext=ext, **kwargs)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/cli.py", line 340, in recursive_write_files
    recursive_write_files(submodule, ext=ext, **kwargs)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/cli.py", line 328, in recursive_write_files
    w.write(m.html(**kwargs))
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/__init__.py", line 789, in html
    html = _render_template('/html.mako', module=self, **kwargs)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/__init__.py", line 133, in _render_template
    return t.render(**config).strip()
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/mako/template.py", line 476, in render
    return runtime._render(self, self.callable_, args, data)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/mako/runtime.py", line 883, in _render
    **_kwargs_for_callable(callable_, data)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/mako/runtime.py", line 920, in _render_context
    _exec_template(inherit, lclcontext, args=args, kwargs=kwargs)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/mako/runtime.py", line 947, in _exec_template
    callable_(context, *args, **kwargs)
  File "_html_mako", line 143, in render_body
  File "_html_mako", line 34, in show_module
  File "_html_mako", line 414, in render_show_module
  File "_html_mako", line 328, in show_func
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/__init__.py", line 1240, in params
    return self._params(self, annotate=annotate, link=link, module=self.module)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/__init__.py", line 1247, in _params
    signature = Function._signature_from_string(doc_obj)
  File "/home/max/code/torchjpeg/.venv/lib/python3.7/site-packages/pdoc/__init__.py", line 1364, in _signature_from_string
    exec('def {}: pass'.format(string), _globals, _locals)
  File "<string>", line 1, in <module>
NameError: name 'at' is not defined

When I print the string variable on that line I can see it is containing:

read_coefficients(path: str) -> Tuple[at::Tensor, at::Tensor, at::Tensor, Optional[at::Tensor]]

but pdoc is trying to exec that as a python function. at:: is a C++ namespace which causes the problem.

Actual Behavior

It works.

Steps to Reproduce
  1. Clone https://gitlab.com/Queuecumber/torchjpeg
  2. pdoc --html --output-dir . --config latex_math=True --force torchjpeg (arguments are likely irrelevant but that's what I use)
  3. Observe error
Additional info
  • pdoc version: 0.8.4

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in pdoc/init.py at Function._signature_from_string, where the traceback shows the pybind11 signature is executed as Python. Reproduce with the torchjpeg repository and the listed pdoc command. Done means documentation generation handles the C++ signature without the NameError.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.