| Message ID | 20250418-library-functions-v1-3-3bbb836149d7@bootlin.com |
|---|---|
| State | Not Applicable |
| Headers | show |
| Series | Document library functions | expand |
Hi Antonin, On 4/18/25 5:15 PM, Antonin Godard via lists.openembedded.org wrote: > 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 --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") > + Isn't that the case for absolutely any Python function taking a string as input? The whole thing is expanded as a normal "hardcoded" string before being passed to the function as argument no? So it feels a bit odd to specify that? No clue how that works with the new string templates (t-string) in Python 3.13 though. > +.. 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())) I don't remember if we allow to build the bitbake docs from outside the bitbake git repo? It is present in poky after all? In that case, maybe we need to use a path relative to conf.py, does Path(.., /lib) do this? Cheers, Quentin
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::
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(+)