RE: [PATCH libgpiod v3 12/16] doc: add documentation for python bindings

[Vincent Fazio <vfazio@xxxxxxxxxxx>]

> -----Original Message-----
> From: Bartosz Golaszewski <brgl@xxxxxxxx>
> Sent: Thursday, February 6, 2025 6:22 AM
> To: Vincent Fazio <vfazio@xxxxxxxxxxx>; Kent Gibson
> <warthog618@xxxxxxxxx>; Linus Walleij <linus.walleij@xxxxxxxxxx>; Erik
> Schilling <erik.schilling@xxxxxxxxxx>; Phil Howard <phil@xxxxxxxxxxxxx>;
> Viresh Kumar <viresh.kumar@xxxxxxxxxx>
> Cc: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>; linux-
> gpio@xxxxxxxxxxxxxxx
> Subject: [External] - [PATCH libgpiod v3 12/16] doc: add documentation for
> python bindings
> 
> From: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> 
> Integrate python docs with sphinx using autodoc and the import mock feature
> which allows us to avoid having to build the C extension.
> 
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> ---
> @@ -50,4 +54,16 @@ except ImportError:
> 
>  html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default"
> 
> +
> +def autodoc_skip_init(app, what, name, obj, would_skip, options):
> +    if name == "__init__":
> +        return False
> +
> +    return would_skip
> +
> +
> +def setup(app):
> +    app.connect("autodoc-skip-member", autodoc_skip_init)
> +
> +

I think you're adding this because of my comment about LineRequest?
https://lore.kernel.org/all/PH1P110MB1603C49CC0A3B2E9CA3C91959F02A@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/

We could optionally remove this and add `:class-doc-from: both` to docs/python_line_request.rst

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-autoclass-class-doc-from

This would drop `__init__` from everything, which should be ok since they largely lack docstrings and duplicate the class documentation about constructor arguments.

In the case where it's added, it will merge the docstring from __init__ to the class docstring.

It may drive updating the docstring for LineRequest.__init__ since it's fine to call methods on the object (and thus use) when it's the return value of a function call, but otherwise not OK to construct the object.