Re: [docs] [PATCH 2/4] conf.py: enable sphinx.ext.graphviz extension

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

On Tue Sep 22, 2026 at 10:17 AM CEST, Antonin Godard wrote:
> Hi,
>
> On Fri Sep 11, 2026 at 5:07 PM CEST, Adrian Freihofer via lists.yoctoproject.org wrote:
>> From: Adrian Freihofer <adrian.freihofer@siemens.com>
>>
>> Required by the .. graphviz:: diagrams added to dev-manual/devtool.rst
>> in a following commit.
>>
>> Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
>> ---
>>  documentation/conf.py | 1 +
>>  1 file changed, 1 insertion(+)
>>
>> diff --git a/documentation/conf.py b/documentation/conf.py
>> index 48d28a686..7144d6db1 100644
>> --- a/documentation/conf.py
>> +++ b/documentation/conf.py
>> @@ -48,6 +48,7 @@ needs_sphinx = "4.0"
>>  extensions = [
>>      'sphinx.ext.autosectionlabel',
>>      'sphinx.ext.extlinks',
>> +    'sphinx.ext.graphviz',
>>      'sphinx.ext.intersphinx',
>>      'sphinx_copybutton',
>>      'sphinxcontrib.rsvgconverter',
>
> In order to add this extension, we also need to update our standards.md document
> to mention the usage of these types of graphics (under "## Adding new
> diagrams"). Also, we need to explain how to edit these graphs - did you use
> software to create them? Which one?
>
> Unrelated, but your series does not apply to master anymore, sorry :/ Could you
> rebase it?

We would also need to update our host requirements for building the
documentation as this extension requires 'dot':

  WARNING: dot command 'dot' cannot be run (needed for graphviz output), check the graphviz_dot setting

So this makes this addition more challenging, as we'll also need to update all
Autobuilder workers to include graphviz. It's possible, of course, but it's
going to take some time.

An alternative I've considered in the past is the addition of the
sphinxcontrib-mermaid extension[1] to our docs. The main advantage I see using
this is that mermaid diagrams are much simpler to read and understand when
reading them textually, so also more maintainable. It looks also slightly more
modern, and has more possibilities, like having our own color theme, etc. Also,
as far as I've tested it, it does not require any additional host dependencies,
it is self-contained.

What do you think?

Can your series be re-sent without graphviz diagrams? And we work on refreshing
diagrams separately, later.

In any case, if this series needs to be merged before 6.1, it would need to be
one without graphviz or mermaid diagrams, as both take time to integrate.

[1]: https://github.com/mgaitan/sphinxcontrib-mermaid

Thanks!
Antonin