Re: [docs] [PATCH] conf.py: silence cve role already registered

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

Hi Quentin,

On Mon Nov 4, 2024 at 11:33 AM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Julien,
>
> On 10/31/24 5:52 PM, Julien Stephan via lists.yoctoproject.org wrote:
>> Commit bd9add8a0 - conf.py: add macro for Mitre CVE links
>> added a new macro for mitre cve links called "cve_mitre" which conflicts
>> with the already existing "cve" role.
>> 
>>    WARNING: role 'cve' is already registered, it will be overridden [app.add_role]
>> 
>> The warning is turned into an error making "make html" fail, but
>> documentation is still successfully built.
>> 
>> Since documentation is still correctly built, just suppress the warning.
>> 
>
> I don't understand the issue and why Sphinx complains about it.
>
> I'm also very wary about just silencing a warning instead of tackling it.

The issue is that newer Sphinx versions are already defining a :cve: role that
points to cve.org, instead of the role we defined in conf.py that points to
nvd.nist.gov. So we have different solutions:

- either override the role to make it point to nvd.nist.gov, which is a bit of a
  hack but works:

  from sphinx.roles import CVE
  CVE._BASE_URL ='https://nvd.nist.gov/vuln/detail/CVE-'

  Also that may not be backwards compatible. Context: we already noticed last
  week that old releases don't build with newer versions of Sphinx, we were thus
  planning on keeping an old Sphinx version for building old doc versions.

- just point to cve.org instead, I'm not sure how important pointing to the nist
  database is. May pose a problem with older sphinx versions, though.

- remove the warning as Julien did. Has the advantage of being backward
  compatible, although not nice to suppress a warning of course.

> I don't understand why this triggers it, extlinks contains an alias with 
> a base URL and a caption. The only overlap we have is the CVE-%s 
> caption. But why would that be an issue, it's just text!

I guess extlinks doesn't really act as an "override existing roles" behavior but
an "append to existing roles and warn if a role already exists".

> Also not sure what Antonin meant with "make the
> links point to NIST, as expected.". Which ones? What's the actual issue
> here we're trying to fix?
>
> Cheers,
> Quentin

Cheers,
Antonin

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