[yocto-docs,07/14] ref-manual/classes: document the cython class

Small class added in oecore by commit
64b6e8580842949be58f97f4dff91d1f097c4020 ("classes-recipe: add cython
class").

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/classes.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

Hi Antonin,

On 12/17/24 10:27 AM, Antonin Godard via lists.yoctoproject.org wrote:
> Small class added in oecore by commit
> 64b6e8580842949be58f97f4dff91d1f097c4020 ("classes-recipe: add cython
> class").
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/ref-manual/classes.rst | 11 +++++++++++
>   1 file changed, 11 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 3d61d8d7a00b21fcff82a771f9718013fae36694..47f049c7435a989f30c033b7b12d86482686ac77 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -614,6 +614,17 @@ You will find some more details in the
>   ":ref:`dev-manual/vulnerabilities:checking for vulnerabilities`"
>   section in the Development Tasks Manual.
>   
> +.. _ref-classes-cython:
> +
> +``cython``
> +==========
> +
> +The :ref:`ref-classes-cython` class can be used by Python recipes that require
> +:oe_git:`Cython </openembedded-core/tree/meta/recipes-devtools/python/python3-cython_3.0.11.bb>`

I'm not entirely sure this is a good idea. This will eventually change 
during a version upgrade and the recipe at that version disappear and 
this link be useless. Two options: no link or a link from a specific 
commit so it is always there.

I am not entirely sure pointing to the Cython recipe provides anything 
meaningful here so I would vote for removing the link (could be a link 
to the Cython project instead?).

> +as part of their build dependencies (:term:`DEPENDS`). It also improves
> +reproducibility for these recipes by stripping potential leftovers build paths
> +in compilation outputs.
> +

I'm not sure the reproducibility improvement need to be mentioned here. 
It seems to me like this could be interpreted as "if you want improved 
reproducibility you can include this class even if the recipe doesn't 
need Cython". If it needs Cython, I assume the leftover issues for 
reproducibility are coming from Cython so it's expected we fix those? 
Not sure it's very clear what I'm trying to convey here?

Cheers,
Quentin

Hi Quentin,

On Tue Dec 17, 2024 at 11:48 AM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 12/17/24 10:27 AM, Antonin Godard via lists.yoctoproject.org wrote:
>> Small class added in oecore by commit
>> 64b6e8580842949be58f97f4dff91d1f097c4020 ("classes-recipe: add cython
>> class").
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/ref-manual/classes.rst | 11 +++++++++++
>>   1 file changed, 11 insertions(+)
>> 
>> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
>> index 3d61d8d7a00b21fcff82a771f9718013fae36694..47f049c7435a989f30c033b7b12d86482686ac77 100644
>> --- a/documentation/ref-manual/classes.rst
>> +++ b/documentation/ref-manual/classes.rst
>> @@ -614,6 +614,17 @@ You will find some more details in the
>>   ":ref:`dev-manual/vulnerabilities:checking for vulnerabilities`"
>>   section in the Development Tasks Manual.
>>   
>> +.. _ref-classes-cython:
>> +
>> +``cython``
>> +==========
>> +
>> +The :ref:`ref-classes-cython` class can be used by Python recipes that require
>> +:oe_git:`Cython </openembedded-core/tree/meta/recipes-devtools/python/python3-cython_3.0.11.bb>`
>
> I'm not entirely sure this is a good idea. This will eventually change 
> during a version upgrade and the recipe at that version disappear and 
> this link be useless. Two options: no link or a link from a specific 
> commit so it is always there.
>
> I am not entirely sure pointing to the Cython recipe provides anything 
> meaningful here so I would vote for removing the link (could be a link 
> to the Cython project instead?).

Of course, I forgot about this.
I will link the Cython project instead.

>> +as part of their build dependencies (:term:`DEPENDS`). It also improves
>> +reproducibility for these recipes by stripping potential leftovers build paths
>> +in compilation outputs.
>> +
>
> I'm not sure the reproducibility improvement need to be mentioned here. 
> It seems to me like this could be interpreted as "if you want improved 
> reproducibility you can include this class even if the recipe doesn't 
> need Cython". If it needs Cython, I assume the leftover issues for 
> reproducibility are coming from Cython so it's expected we fix those? 
> Not sure it's very clear what I'm trying to convey here?

Yes, and there must other places where reproducibility is improved and the docs
doesn't mention it. I'll remove this.


Thanks!
Antonin