On 11/18/2026 7:31 AM, Alex Bennée wrote:
> Pierrick Bouvier <[email protected]> writes:
> 
>> On 11/6/2026 12:36 PM, Alex Bennée wrote:
>>> Pierrick Bouvier <[email protected]> writes:
>>>
>>>> On 11/6/2026 4:21 AM, Alex Bennée wrote:
>>>>> We've had various versions of this diagram for a while so I thought it
>>>>> would be worth adding to the developer docs. I chose plantuml as it
>>>>> has a plugin for sphinx that we can use and supports sequence diagrams
>>>>> which could be useful for documenting other features in the code base.
>>>>>
>>>>> Signed-off-by: Alex Bennée <[email protected]>
>>>>>
>>>>> ---
>>>>> vRFC
>>>>>   - I've bundled all the plumbing together in this commit but it can
>>>>>   be split up if we want to go forward.
>>>>> ---
> <snip>
>>>>> diff --git a/tests/lcitool/projects/qemu.yml 
>>>>> b/tests/lcitool/projects/qemu.yml
>>>>> index abbd3e3f0b8..de4395cd3c7 100644
>>>>> --- a/tests/lcitool/projects/qemu.yml
>>>>> +++ b/tests/lcitool/projects/qemu.yml
>>>>> @@ -89,6 +89,7 @@ packages:
>>>>>   - pcre-static
>>>>>   - pixman
>>>>>   - pkg-config
>>>>> + - plantuml
>>>>>   - pulseaudio
>>>>>   - python3
>>>>>   - python3-numpy
>>>>
>>>> It will silently disable doc by default for most of the people
>>>> unfortunately, not sure it's the best move we can do.
> 
> Do most people build the docs? As long as it fails hard for
> --enable-docs I think that should be OK right? Especially if we update
> the min requirements for the project.
>

If we start with the assumption that it's ok for people to not build
docs when submitting patches, then it's ok for sure. Is that right?
that's another question.

>>>
>>> plantuml seems to be pretty widely packaged so in this sense its just
>>> another dependency.
>>>
>>>> Maybe a simpler solution could be to generate diagrams out of sphinx,
>>>> add them as a dependency, and generate a blank image (or an image with
>>>> diagram source and a message - please install plantuml) if not
>>>> available. What does plantuml brings compares to graphviz builtin
>>>> extension?
>>>
>>> Ohh I didn't realize there was graphviz - I'll see if I can recreate
>>> with that.
>>>
>>
>> If graphviz is not installed, a warning is emitted, which stops the
>> build since we turn warnings into error.
>>
>> The warning emitted has no type, so it can't be filtered with
>> suppress_warning setting from sphinx-build.
>>
>> However, since sphinx uses standard logging framework, you can silence
>> it this way: https://github.com/sphinx-doc/sphinx/issues/10219
>>
>> ```
>> --- a/docs/conf.py
>> +++ b/docs/conf.py
>> @@ -24,6 +24,7 @@
>> +import logging
>>  import os
>>  import sys
>>  import sphinx
>> @@ -66,8 +67,20 @@
>>      'qapi_domain',
>>      'qapidoc',
>>      'qmp_lexer',
>> +    'sphinx.ext.graphviz',
>>  ]
>>
>> +# Render graphviz diagrams as SVG so they scale cleanly in HTML output.
>> +graphviz_output_format = 'svg'
>> +
>> +# Silence the warning emitted by sphinx.ext.graphviz when 'dot' is not
>> +# installed. Diagrams are then rendered as their raw source instead.
>> +class _NoDotWarning(logging.Filter):
>> +    def filter(self, record):
>> +        return 'cannot be run (needed for graphviz output)' not in
>> record.getMessage()
>> +
>> +logging.getLogger('sphinx.sphinx.ext.graphviz').addFilter(_NoDotWarning())
>> ```
>>
>> The advantage is that graphviz is not a required dependency, so doc is
>> still built for anyone having sphinx installed. That's a nice end result
>> I think.
> 
> I don't know - silently building a not quite complete set of docs seems
> like the wrong way around but I'm happy to defer to the distro folks
> here.
>

I don't mind blocking the build if you feel it's better.

The important IMHO, is that graphviz is a better choice than plantuml:
it's supported out of the box with sphinx, and avoid to add a transitive
(heavy) dependency to java for the project.

>>
>>>> Also, text diagrams (https://asciidraw.github.io/) with raw formatting
>>>> have the advantage to not require any external tool.
>>>
>>> I have the ascii original although ditaa seemed more of a stretch:
>>>
> <snip>
> 

Regards,
Pierrick

Reply via email to