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
