mitmproxy / pdoc

API Documentation for Python Projects
https://pdoc.dev
MIT No Attribution
1.96k stars 193 forks source link

Magic method are not documented #204

Closed pprados closed 3 years ago

pprados commented 3 years ago

Problem Description

With a class with magic method (get(), contains(), ...), the documentation are not generated. I try to add these methods in doc

  __pdoc__ = {
      "grid.Grid.__get__": True,

Without result

Steps to reproduce the behavior:

  1. Create a class with magic method and docstring
  2. generate the doc

System Information

pdoc 0.9.2

mhils commented 3 years ago

Hi @pprados,

It looks like you have installed pdoc3, not pdoc (see pdoc3 vs. pdoc3). You may want to run pip uninstall pdoc3 and then pip install pdoc.

We generally discourage documenting individual __dunder__ methods. Have you considered giving some examples in your class docstring instead? I often feel that's much more useful for your readers.

If you definitely want to document your __dunder__ methods, you can use a custom template with pdoc 2.0. Here's the relevant part in the documentation: https://pdoc.dev/docs/pdoc.html#control-what-is-documented

pprados commented 3 years ago

pdoc3 is not installed.

pip uninstall pdoc3
WARNING: Skipping pdoc3 as it is not installed.

But thanks. I will try to use the template.

mhils commented 3 years ago

To clarify, there never was a pdoc 0.9.x release. Just make sure that you get 2.0 or above when running it :)