Re: [PATCH] conf.py: rename :cve: role to :cve_nist:

["Antonin Godard" <antonin.godard@bootlin.com>]

On Mon Nov 4, 2024 at 3:06 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 11/4/24 2:31 PM, Antonin Godard wrote:
>> On Mon Nov 4, 2024 at 1:55 PM CET, Quentin Schulz wrote:
>>> Hi Antonin,
>>>
>>> On 11/4/24 1:39 PM, Antonin Godard wrote:
>>>> Newer versions of Sphinx already define a :cve: role that points to
>>>> cve.org, instead of the role we defined in conf.py that points to
>>>> nvd.nist.gov.
>>>>
>>>> Rename our role to :cve_nist: to avoid warnings (treated as errors).
>>>> This is also backwards compatible, meaning we can build the doc with an
>>>> older Sphinx if needed.
>>>>
>>>> Suggested-By: Quentin Schulz <quentin.schulz@cherry.de>
>>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>>
>>> Looks good to me. I assume you didn't change those by hand, maybe add
>>> the command you used to do the migration so we can figure out if
>>> something's been left out inadvertently? (Would be useful if we figure
>>> out in the future that this missed something so we can more easily find
>>> a programmatic way of fixing the left-out instead of finding and fixing
>>> them by hand?).
>> 
>> Hmm... I used my editor, but the equivalent one-liner is:
>> 
>> find . -name '*.rst' -exec sed -i 's/:cve:/:cve_nist:/g' {} \+
>> 
>> Which I'll add to the commit message.
>> 
>>> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>>>
>>> (Admittedly only reviewed the conf.py part :) ).
>>>
>>> For backporting, we'll likely need a new patch on the autobuilder, c.f.
>>> https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/docs-build-patches
>>> since we want to build tags which we cannot move.
>> 
>> If I understand correctly, these are patches to apply to old documentation
>> versions? To extend my reasoning on this, since new tags were added recently for
>> old doc versions, should I update `missing_tags` and add corresponding patches
>> there? I'm a bit clueless :)
>> 
>
> I haven't really checked what the ramifications are for those new tags. 
> It's possible it fixes a bunch of stuff that we needed to work around. 
> Maybe we don't even need that missing_tags logic anymore at all in 
> set_versions.py. But that would only fix the generation of the 
> releases.rst file, which is different from fixing content of old 
> unmaintained releases for newer Sphinx versions, which is handled in the 
> yocto-autobuilder. I think they aren't related here but haven't spent 
> some time recently on that so cannot tell right now.

Thanks for the added context! I'll see how this goes…

> Cheers,
> Quentin

Cheers,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com