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
