diff mbox series

[3/4] doc: add a new Library Functions document

Message ID 20250418-library-functions-v1-3-3bbb836149d7@bootlin.com
State New
Headers show
Series Document library functions | expand

Commit Message

Antonin Godard April 18, 2025, 3:15 p.m. UTC 
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]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 .../bitbake-user-manual-library-functions.rst      | 59 ++++++++++++++++++++++
 doc/conf.py                                        |  7 +++
 doc/index.rst                                      |  1 +
 3 files changed, 67 insertions(+)
diff mbox series

Patch

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-library-functions.rst b/doc/bitbake-user-manual/bitbake-user-manual-library-functions.rst
new file mode 100644
index 000000000..09e353945
--- /dev/null
+++ b/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/doc/conf.py b/doc/conf.py
index fc2ee0811..f61241e28 100644
--- a/doc/conf.py
+++ b/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/doc/index.rst b/doc/index.rst
index ee1660ac1..546ef36c1 100644
--- a/doc/index.rst
+++ b/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::