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.

>> 
>> 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.

>
>>> 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>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Reply via email to