All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Alex Bennée" <alex.bennee@linaro.org>
To: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
Cc: qemu-devel@nongnu.org,  Paolo Bonzini <pbonzini@redhat.com>,
	 John Snow <jsnow@redhat.com>,
	 Peter Maydell <peter.maydell@linaro.org>,
	 Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Subject: Re: [RFC PATCH] docs: add a diagram of the development process
Date: Wed, 18 Nov 2026 15:31:26 +0000	[thread overview]
Message-ID: <87zev65f75.fsf@draig.linaro.org> (raw)
In-Reply-To: <b6a6e0bc-90b0-4162-8ec9-098d1ced1069@oss.qualcomm.com> (Pierrick Bouvier's message of "Fri, 6 Nov 2026 13:01:33 -0800")

Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com> writes:

> On 11/6/2026 12:36 PM, Alex Bennée wrote:
>> Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com> 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 <alex.bennee@linaro.org>
>>>>
>>>> ---
>>>> 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


  parent reply	other threads:[~2026-11-18 15:31 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-06 12:21 [RFC PATCH] docs: add a diagram of the development process Alex Bennée
2026-11-06 17:38 ` Pierrick Bouvier
2026-11-06 20:36   ` Alex Bennée
2026-11-06 21:01     ` Pierrick Bouvier
2026-11-09 11:01       ` Philippe Mathieu-Daudé
2026-11-18 15:31       ` Alex Bennée [this message]
2026-11-18 15:58         ` Pierrick Bouvier

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87zev65f75.fsf@draig.linaro.org \
    --to=alex.bennee@linaro.org \
    --cc=jsnow@redhat.com \
    --cc=mchehab+huawei@kernel.org \
    --cc=pbonzini@redhat.com \
    --cc=peter.maydell@linaro.org \
    --cc=pierrick.bouvier@oss.qualcomm.com \
    --cc=qemu-devel@nongnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.