Openembedded Core Discussions
 help / color / mirror / Atom feed
* [PATCH 00/13] Improve or add oe.* library docstrings
@ 2026-11-16 16:08 Antonin Godard
  2026-11-16 16:08 ` [PATCH 01/13] lib/oe/path: rename "metadata" parameter to "d" Antonin Godard
                   ` (12 more replies)
  0 siblings, 13 replies; 15+ messages in thread
From: Antonin Godard @ 2026-11-16 16:08 UTC (permalink / raw)
  To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni

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


^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2026-11-17 10:09 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
2026-11-16 16:08 ` [PATCH 01/13] lib/oe/path: rename "metadata" parameter to "d" Antonin Godard
2026-11-16 16:09 ` [PATCH 02/13] oe/path: simplify replace_absolute_symlinks() signature Antonin Godard
2026-11-16 16:09 ` [PATCH 03/13] lib/oe/utils: simplify str_filter*() signatures Antonin Godard
2026-11-16 16:09 ` [PATCH 04/13] lib/oe/utils: drop all_multilib_tune_list Antonin Godard
2026-11-16 16:09 ` [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu Antonin Godard
2026-11-17 10:09   ` [OE-core] " Mathieu Dubois-Briand
2026-11-16 16:09 ` [PATCH 06/13] lib/oe/data: improve docstring for typed_value Antonin Godard
2026-11-16 16:09 ` [PATCH 07/13] lib/oe/go: detail map_arch() parameter Antonin Godard
2026-11-16 16:09 ` [PATCH 08/13] lib/oe/kernel: convert comments to docstrings and improve Antonin Godard
2026-11-16 16:09 ` [PATCH 09/13] lib/oe/lsb: improve docstrings Antonin Godard
2026-11-16 16:09 ` [PATCH 10/13] lib/oe/path: " Antonin Godard
2026-11-16 16:09 ` [PATCH 11/13] lib/oe/purl: " Antonin Godard
2026-11-16 16:09 ` [PATCH 12/13] lib/oe/utils: " Antonin Godard
2026-11-16 16:09 ` [PATCH 13/13] lib/oe/types: " Antonin Godard

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox