classes: update Python class documentation

Signed-off-by: Ross Burton <ross.burton@arm.com>
---
 documentation/ref-manual/classes.rst | 61 ++++++++++++++++------------
 1 file changed, 36 insertions(+), 25 deletions(-)

Hi Ross,

Thanks for the patch!

On 3/16/22 19:33, Ross Burton wrote:
> Signed-off-by: Ross Burton <ross.burton@arm.com>
> ---
>  documentation/ref-manual/classes.rst | 61 ++++++++++++++++------------
>  1 file changed, 36 insertions(+), 25 deletions(-)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 4dd0901623..60fcd98928 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -602,22 +602,6 @@ variables are not met, the recipe will be skipped, and if the
>  build system attempts to build the recipe then an error will be
>  triggered.
>  
> -.. _ref-classes-flit_core:
> -
> -``flit_core.bbclass``
> -=====================
> -
> -The ``flit_core`` class enables building Python modules which declare
> -the  `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
> -``flit_core.buildapi`` ``build-backend`` in the ``[build-system]``
> -section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
> -
> -Python modules built with ``flit_core.buildapi`` are pure Python (no
> -``C`` or ``Rust`` extensions).
> -
> -The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__)
> -is installed with the :ref:`python_pep517 <ref-classes-python_pep517>` class.
> -
>  .. _ref-classes-fontcache:
>  
>  ``fontcache.bbclass``
> @@ -1978,20 +1962,48 @@ When inherited by a recipe, the ``perlnative`` class supports using the
>  native version of Perl built by the build system rather than using the
>  version provided by the build host.
>  
> +.. _ref-classes-python_flit_core:
> +
> +``python_flit_core.bbclass``
> +=====================
> +
> +The ``python_flit_core`` class enables building Python modules which declare
> +the  `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
> +``flit_core.buildapi`` ``build-backend`` in the ``[build-system]``
> +section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
> +
> +Python modules built with ``flit_core.buildapi`` are pure Python (no
> +``C`` or ``Rust`` extensions).
> +
> +Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
> +
>  .. _ref-classes-python_pep517:
>  
>  ``python_pep517.bbclass``
>  =============================
>  
> -The ``python_pep517`` class installs a Python ``wheel`` binary archive (see
> -`PEP-517 <https://peps.python.org/pep-0517/>`__).
> +The ``python_pep517`` class builds and installs a Python ``wheel`` binary
> +archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__).
> +
> +Recipes wouldn't inherit this directly, instead typically another class will
> +inherit this, add the relevant native dependencies, and set
> +:term:`PEP517_BUILD_API` to the Python class which implements the PEP-517 build
> +API.
> +
> +Examples of classes which do this are :ref:`python_flit_core
> +<ref-classes-python_flit_core>`, :ref:`setuptools_build_meta
> +<ref-classes-setuptools_build_meta>`, and :ref:`python_poetry_core
> +<ref-classes-python_poetry_core>`.
> +
> +.. _ref-classes-python_poetry_core:
> +
> +``python_poetry_core.bbclass``
> +=====================
>  
> -The Python ``wheel`` can be built with several classes, including :ref:`flit_core <ref-classes-flit_core>`,
> -:ref:`setuptools_build_meta <ref-classes-setuptools_build_meta>`, and :ref:`setuptools3 <ref-classes-setuptools3>`.
> +The ``python_poetry_core`` class enables building Python modules which use the
> +`Poetry Core <https://python-poetry.org>`__ build system.
>  
> -The path to the wheel to be installed is defined by :term:`PEP517_WHEEL_PATH`.
> -This defaults to ``${D}/dist`` and should be respected by the builder class
> -(such as :ref:`flit_core <ref-classes-flit_core>`).
> +Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
>  
>  .. _ref-classes-pixbufcache:
>  
> @@ -2362,8 +2374,7 @@ section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep
>  Python modules built with ``setuptools.build_meta`` can be pure Python or
>  include ``C`` or ``Rust`` extensions).
>  
> -The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__)
> -is installed with the :ref:`python_pep517 <ref-classes-python_pep517>` class.
> +Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
>  
>  .. _ref-classes-setuptools3:


The contents look good, but I've got issues at compile time (using
Sphinx 4.4):

/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/ref-manual/classes.rst:1968:
WARNING: Title underline too short.

``python_flit_core.bbclass``
=====================
/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/ref-manual/classes.rst:1968:
WARNING: Title underline too short.

``python_flit_core.bbclass``
=====================
/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/ref-manual/classes.rst:2001:
WARNING: Title underline too short.

``python_poetry_core.bbclass``
=====================
/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/ref-manual/classes.rst:2001:
WARNING: Title underline too short.

``python_poetry_core.bbclass``
=====================
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/ref-manual/classes.rst:1988:
WARNING: term not in glossary: PEP517_BUILD_API

Could you add a description for PEP517_BUILD_API?
Thanks again
Michael.