[yocto-docs] test-manual/ptest: link to common framework ptest classes

We document how to add ptest support for a recipe by inheriting the
ptest class. We may as well tell the user to inherit a ptest class for a
common framework which does most of the job for you.

Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/test-manual/ptest.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)


---
base-commit: 6b44257874858db3aa426d3e84a79c41cb4937a3
change-id: 20250117-ptest-common-classes-25e9b4dc0968

Best regards,

Hi Antonin,

On 1/17/25 3:19 PM, Antonin Godard wrote:
> We document how to add ptest support for a recipe by inheriting the
> ptest class. We may as well tell the user to inherit a ptest class for a
> common framework which does most of the job for you.
> 
> Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/test-manual/ptest.rst | 13 +++++++++++++
>   1 file changed, 13 insertions(+)
> 
> diff --git a/documentation/test-manual/ptest.rst b/documentation/test-manual/ptest.rst
> index dea1bad23bd98817a2020030efdad7ce4e4b36c0..d5a0d007ac118ced77c06b141d4e681f81e60cd2 100644
> --- a/documentation/test-manual/ptest.rst
> +++ b/documentation/test-manual/ptest.rst
> @@ -61,6 +61,19 @@ test. Here is what you have to do for each recipe:
>   
>         inherit ptest
>   
> +   .. note::
> +
> +      Existing class for common frameworks already exist in

s/Existing class/Classes/

> +      :oe_git:`openembedded-core </openembedded-core>`, such as:

A bit of an odd choice to link to the git repo here? Don't we want 
:term:`OpenEmbedded-Core (OE-Core)` instead? or at least point to 
meta/classes-recipe/ directory?

> +
> +      -  :oe_git:`meta/classes-recipe/go-ptest </openembedded-core/tree/meta/classes-recipe/go-ptest.bbclass>`
> +      -  :oe_git:`meta/classes-recipe/ptest-cargo </openembedded-core/tree/meta/classes-recipe/ptest-cargo.bbclass>`
> +      -  :oe_git:`meta/classes-recipe/ptest-perl </openembedded-core/tree/meta/classes-recipe/ptest-perl.bbclass>`
> +      -  :oe_git:`meta/classes-recipe/ptest-python-pytest </openembedded-core/tree/meta/classes-recipe/ptest-python-pytest.bbclass>`
> +

Now to come to think of it... Maybe all of this would be more 
straightforward if we added sections in ref-manual/classes.rst for each 
special ptest class? Then we just have to point at those via the usual 
mechanism of :ref:`ref-classes-<>`? We could also explain a few 
class-specific variables, like PTEST_PYTEST_DIR, GOPTESTBUILDFLAGS, 
GOPTESTFLAGS (though those two are in go.bbclass for some reason), 
RUST_TEST_ARGS, CARGO_TEST_BINARIES_FILES to only name those.
If you prefer to stay with the links for now, I would recommend to only 
keep the name of the class as that's what will matter to the user (to 
pass it to "inherit" directive).

Cheers,
Quentin

Hi Quentin,

On Thu Jan 23, 2025 at 3:18 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 1/17/25 3:19 PM, Antonin Godard wrote:
>> We document how to add ptest support for a recipe by inheriting the
>> ptest class. We may as well tell the user to inherit a ptest class for a
>> common framework which does most of the job for you.
>> 
>> Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/test-manual/ptest.rst | 13 +++++++++++++
>>   1 file changed, 13 insertions(+)
>> 
>> diff --git a/documentation/test-manual/ptest.rst b/documentation/test-manual/ptest.rst
>> index dea1bad23bd98817a2020030efdad7ce4e4b36c0..d5a0d007ac118ced77c06b141d4e681f81e60cd2 100644
>> --- a/documentation/test-manual/ptest.rst
>> +++ b/documentation/test-manual/ptest.rst
>> @@ -61,6 +61,19 @@ test. Here is what you have to do for each recipe:
>>   
>>         inherit ptest
>>   
>> +   .. note::
>> +
>> +      Existing class for common frameworks already exist in
>
> s/Existing class/Classes/
>
>> +      :oe_git:`openembedded-core </openembedded-core>`, such as:
>
> A bit of an odd choice to link to the git repo here? Don't we want 
> :term:`OpenEmbedded-Core (OE-Core)` instead? or at least point to 
> meta/classes-recipe/ directory?

Didn't think of using the :term: here, will change.

>> +
>> +      -  :oe_git:`meta/classes-recipe/go-ptest </openembedded-core/tree/meta/classes-recipe/go-ptest.bbclass>`
>> +      -  :oe_git:`meta/classes-recipe/ptest-cargo </openembedded-core/tree/meta/classes-recipe/ptest-cargo.bbclass>`
>> +      -  :oe_git:`meta/classes-recipe/ptest-perl </openembedded-core/tree/meta/classes-recipe/ptest-perl.bbclass>`
>> +      -  :oe_git:`meta/classes-recipe/ptest-python-pytest </openembedded-core/tree/meta/classes-recipe/ptest-python-pytest.bbclass>`
>> +
>
> Now to come to think of it... Maybe all of this would be more 
> straightforward if we added sections in ref-manual/classes.rst for each 
> special ptest class? Then we just have to point at those via the usual 
> mechanism of :ref:`ref-classes-<>`? We could also explain a few 
> class-specific variables, like PTEST_PYTEST_DIR, GOPTESTBUILDFLAGS, 
> GOPTESTFLAGS (though those two are in go.bbclass for some reason), 
> RUST_TEST_ARGS, CARGO_TEST_BINARIES_FILES to only name those.
> If you prefer to stay with the links for now, I would recommend to only 
> keep the name of the class as that's what will matter to the user (to 
> pass it to "inherit" directive).

Having some doc for each class would be sweet, I agree. It's a bit more work, so
we can delay that for later. Having links is a first step.

Thanks,
Antonin