Hi Milan,

Thanks for the patch!

On Fri, Mar 12, 2021 at 06:06:43PM +0530, Milan Shah wrote:
> A number of functions in lib/bb/utils.py are used throughout the meta*/ recipe
> and bbclass files. Unfortunately the methods for the class are not documented.
>
> Added a new "library functions" section to the manual in the reference manual
> in the yocto-docs repository and document the utils functions to start with.
>
> See [YOCTO #9612] for the details.
>
> Signed-off-by: Milan Shah <mshah@mvista.com>

[...]

> +``contains``
> +--------------
> +
> +Check if a variable contains all the values specified.
> +
> +Arguments:
> +
> +    `variable` -- the variable name. This will be fetched and expanded (using d.getVar(variable)) and then split into a set().
> +
> +    `checkvalues` -- if this is a string it is split on whitespace into a set(), otherwise coerced directly into a set().
> +
> +    `truevalue` -- the value to return if checkvalues is a subset of variable.
> +    `falsevalue` -- the value to return if variable is empty or if checkvalues is not a subset of variable.
> +
> +    `d` -- the data store.
> +
> +
> +
> +See the occurrence in :term:`TUNE_ASARGS` , :term:`TUNE_LDARGS` , :ref:`image_types.bbclass <ref-classes-image_types>` , and :ref:`migration-1.8-bluez` sections.
> +

I'm not sure it makes much sense to duplicate documentation.

I see an absolute need for bb.utils functions to be documented
thoroughly in code, where they are implemented.

e.g. https://git.yoctoproject.org/cgit.cgi/poky/tree/bitbake/lib/bb/utils.py#n983

This seems to be the case for most functions, which is a good thing.

What I am afraid with your patch is that nobody will take care of
maintaining this copy of the documention from bb.utils code when there
will be changes, deletions or additions.

Since one should be able to extract Python docstring from a python file
with e.g. bb.utils.contains.__doc__, it should be possible to have
something autogenerated and thus, auto-maintained.
You can probably iterate over all functions defined in a Python module
too.

Also, I'd probably see this kind of documentation more in Bitbake docs
than YP docs (or both).

I'd see something similar to what Pillow is doing here:
https://pillow.readthedocs.io/en/stable/reference/Image.html#functions
which links to:
https://pillow.readthedocs.io/en/stable/_modules/PIL/Image.html#open
if one wants to see the source code.

With a quick google search, I found this:
https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

It probably could be something that we add to our release scripts and
then somehow add the resulting rst/html to the bitbake docs. No idea how
to hook this up though, just giving ideas (and complaining :) ).

Cheers,
Quentin