From a035cd4718e60c1cd1a7b4c679f9fda177ce1c32 Mon Sep 17 00:00:00 2001
From: Antonin Godard <antonin.godard@bootlin.com>
Date: Fri, 18 Apr 2025 17:15:27 +0200
Subject: [PATCH] bitbake: doc: add a new Library Functions document

Add a new document to the BitBake user manual that automatically
documents the library functions from their docstrings. The docstrings
can be formatted in reStructuredText.

Here logging utilities and the bb.utils module is documented. Some
members of the utils module were deliberately excluded as their usage is
most likely only internal to BitBake.

Fixes [YOCTO #9612]

(Bitbake rev: 0a711949acc2696f32a61c591ee3ea37041acb91)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Mathieu Dubois-Briand <mathieu.dubois-briand@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../bitbake-user-manual-library-functions.rst | 59 +++++++++++++++++++
 bitbake/doc/conf.py                           |  7 +++
 bitbake/doc/index.rst                         |  1 +
 3 files changed, 67 insertions(+)
 create mode 100644 bitbake/doc/bitbake-user-manual/bitbake-user-manual-library-functions.rst

diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-library-functions.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-library-functions.rst
new file mode 100644
index 0000000000..09e353945b
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-library-functions.rst
@@ -0,0 +1,59 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+=================
+Library Functions
+=================
+
+|
+
+This chapter lists common library functions available under the ``lib/``
+directory in BitBake.
+
+These functions can be used in recipes or configuration files with
+:ref:`inline-Python <bitbake-user-manual/bitbake-user-manual-metadata:Inline
+Python Variable Expansion>` or :ref:`Python
+<bitbake-user-manual/bitbake-user-manual-metadata:BitBake-Style Python
+Functions>` functions.
+
+Logging utilities
+=================
+
+Different logging utilities can be used from Python code in recipes or
+configuration files.
+
+The strings passed below can be formatted with ``str.format()``, for example::
+
+   bb.warn("Houston, we have a %s", "bit of a problem")
+
+Formatted string can also be used directly::
+
+   bb.error("%s, we have a %s" % ("Houston", "big problem"))
+
+Python f-strings may also be used::
+
+   h = "Houston"
+   bb.fatal(f"{h}, we have a critical problem")
+
+.. automodule:: bb
+   :members:
+      debug,
+      error,
+      erroronce,
+      fatal,
+      note,
+      plain,
+      verbnote,
+      warn,
+      warnonce,
+
+``bb.utils``
+============
+
+.. automodule:: bb.utils
+   :members:
+   :exclude-members:
+      LogCatcher,
+      PrCtlError,
+      VersionStringException,
+      better_compile,
+      better_exec,
diff --git a/bitbake/doc/conf.py b/bitbake/doc/conf.py
index fc2ee08111..f61241e28b 100644
--- a/bitbake/doc/conf.py
+++ b/bitbake/doc/conf.py
@@ -17,6 +17,8 @@
 import sys
 import datetime
 
+from pathlib import Path
+
 current_version = "dev"
 
 # String used in sidebar
@@ -47,6 +49,7 @@ extlinks = {
 extensions = [
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.extlinks',
+    'sphinx.ext.autodoc',
 ]
 autosectionlabel_prefix_document = True
 
@@ -99,3 +102,7 @@ html_last_updated_fmt = '%b %d, %Y'
 
 # Remove the trailing 'dot' in section numbers
 html_secnumber_suffix = " "
+
+# autoconf needs the modules available to auto-generate documentation from the
+# code
+sys.path.insert(0, str(Path('..', 'lib').resolve()))
diff --git a/bitbake/doc/index.rst b/bitbake/doc/index.rst
index ee1660ac15..546ef36c16 100644
--- a/bitbake/doc/index.rst
+++ b/bitbake/doc/index.rst
@@ -16,6 +16,7 @@ BitBake User Manual
    bitbake-user-manual/bitbake-user-manual-ref-variables-context
    bitbake-user-manual/bitbake-user-manual-fetching
    bitbake-user-manual/bitbake-user-manual-ref-variables
+   bitbake-user-manual/bitbake-user-manual-library-functions
    bitbake-user-manual/bitbake-user-manual-hello
 
 .. toctree::