mbox series

[00/13] Improve or add oe.* library docstrings

Message ID 20261116-oe-lib-docstrings-v1-0-0c894f6a1064@bootlin.com
Headers show
Series Improve or add oe.* library docstrings | expand

Message

Antonin Godard Nov. 16, 2026, 4:08 p.m. UTC
Improve the docstrings of useful oe library modules and format them for
inclusion with the sphinx.ext.autodoc extension. This allows presenting
the documentation like in [1].

The series is divided in two parts:

- Patch 01 to 05 are code fixups, they do not contains documentation
  changes, but are relevant to provide a meaningful and consistent
  documentation.

  Some are breaking changes and scould be debated, but I believe for
  most it does make sense to make the change, especially for
  understanding how the function works in documentation.

- Patch 06 to the last patch are only docstrings changes, one patch per
  oe module to make reviewing easier.

This work will be integrated to the yocto-docs documentation in separate
series, sent after this one.

Note: compared to [1], I deliberately stopped following the
"Parameters:" and "Returns ..." pattern as it sometimes proved to be
challenging to describe the function's behavior in a natural way.
Instead, I took inspiration from how the Python library documents its
own modules, using imperative tense and simple paragraphs (most of the
time).

Note 2: for now, only certain modules are covered, especially those that I
think are useful for end-users. Some functions in those modules are not
documented and were left as-is because I also felt it wasn't useful to
document them.

[1]: https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-library-functions.html

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (13):
      lib/oe/path: rename "metadata" parameter to "d"
      oe/path: simplify replace_absolute_symlinks() signature
      lib/oe/utils: simplify str_filter*() signatures
      lib/oe/utils: drop all_multilib_tune_list
      lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu
      lib/oe/data: improve docstring for typed_value
      lib/oe/go: detail map_arch() parameter
      lib/oe/kernel: convert comments to docstrings and improve
      lib/oe/lsb: improve docstrings
      lib/oe/path: improve docstrings
      lib/oe/purl: improve docstrings
      lib/oe/utils: improve docstrings
      lib/oe/types: improve docstrings

 meta/classes-recipe/testimage.bbclass            |   2 +-
 meta/classes/relative_symlinks.bbclass           |   2 +-
 meta/lib/oe/data.py                              |  28 ++-
 meta/lib/oe/go.py                                |   7 +-
 meta/lib/oe/kernel.py                            |  22 +-
 meta/lib/oe/lsb.py                               |  18 +-
 meta/lib/oe/path.py                              | 154 ++++++++++----
 meta/lib/oe/purl.py                              |   9 +-
 meta/lib/oe/qemu.py                              |  24 +++
 meta/lib/oe/types.py                             | 166 +++++++++++----
 meta/lib/oe/utils.py                             | 254 +++++++++++++++++------
 meta/lib/oeqa/selftest/cases/efibootpartition.py |   2 +-
 meta/lib/oeqa/selftest/cases/runqemu.py          |   2 +-
 meta/lib/oeqa/selftest/cases/uki.py              |   2 +-
 meta/lib/oeqa/targetcontrol.py                   |   2 +-
 15 files changed, 529 insertions(+), 165 deletions(-)
---
base-commit: f32bced7b431f39a956c3e0d42e3c756ab784c49
change-id: 20261103-oe-lib-docstrings-355ea9d439b5