Re: [docs] [PATCH v3 3/4] dev-manual/devtool: add diagrams for the ide-sdk workflow and architecture

["Antonin Godard" <antonin.godard@bootlin.com>]

On Thu Oct 15, 2026 at 10:06 PM CEST, Adrian Freihofer via lists.yoctoproject.org wrote:
> From: Adrian Freihofer <adrian.freihofer@siemens.com>
>
> Add three diagrams to the devtool ide-sdk section: a typical usage
> workflow, the architecture of the SDK/IDE relationship, and a variant
> of the architecture for the --nfs=rootfs-dbg mode.
>
> The diagrams are Mermaid (.mmd) flowcharts, kept as the maintainable
> source next to the pre-rendered SVGs that the documentation includes,
> so building the documentation needs no Mermaid tooling. The command to
> regenerate an SVG is documented at the top of each .mmd file. The
> Mermaid configuration in each .mmd follows the documentation SVG
> policy (GNOME HIG colors, Nimbus Roman 10pt text, rounded boxes, no
> shadows).
>
> Colors: blue for the SDK/build environment, purple for devtool-managed
> workspace/NFS directories, brown for the target device, orange for
> entry-point commands and green for editable/source elements.
>
> The images are scaled with the page width but never beyond their
> natural size, which is what the new max-natural-size CSS class is for.
> The text then stays at the intended size.
>
> Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
> ---
>  documentation/dev-manual/devtool.rst          | 27 +++++-
>  .../figures/devtool-ide-sdk-architecture.mmd  | 84 +++++++++++++++++

I don't think it is necessary to keep the mmd files. As I said in v2, you can
probably keep those as comments in the SVG, starting the SVG file with:

  <!--
     <your mmd content here...>
  -->
  <svg...

The problem with keeping the mmd is that some people may modify the SVGs
directly and the two files would become unsynced - and we recommend Inkscape for
editing SVGs.

Also regarding the font, thanks for using Nimbus Roman, it is what the standards
file say. However I'm not sure why we should be limited to Nimbus *Roman*, as
serif fonts clearly don't look good to me in diagrams. I know this contradicts
the standards file, but I think Nimbus Sans would look better here. If that's
ok, let's change the font to Nimbus Sans, and I'll adjust the standards.md file
later. Otherwise, I can do a pass on your diagrams after they're merged, later.

>  .../figures/devtool-ide-sdk-architecture.svg  |  1 +

For this diagram there's a typo: "(build directory) build artifacts)"

>  .../devtool-ide-sdk-nfs-architecture.mmd      | 89 +++++++++++++++++++
>  .../devtool-ide-sdk-nfs-architecture.svg      |  1 +
>  .../figures/devtool-ide-sdk-workflow.mmd      | 74 +++++++++++++++
>  .../figures/devtool-ide-sdk-workflow.svg      |  1 +
>  .../sphinx-static/theme_overrides.css         |  5 ++
>  8 files changed, 279 insertions(+), 3 deletions(-)
>  create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-architecture.mmd
>  create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-architecture.svg
>  create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.mmd
>  create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-nfs-architecture.svg
>  create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-workflow.mmd
>  create mode 100644 documentation/dev-manual/figures/devtool-ide-sdk-workflow.svg
>
> diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst
> index e182b427b..ba0435a46 100644
> --- a/documentation/dev-manual/devtool.rst
> +++ b/documentation/dev-manual/devtool.rst
> @@ -480,7 +480,14 @@ directly in the IDE, independently of ``devtool ide-sdk`` and without calling
>  configuration that points the IDE directly at the build tool, the
>  cross-toolchain and the debugger provided by the SDK. ``devtool ide-sdk``
>  only needs to be re-run later on, e.g. if a recipe's dependencies or its
> -build configuration change.
> +build configuration change:
> +
> +.. image:: figures/devtool-ide-sdk-workflow.svg

You should do:

.. image:: figures/devtool-ide-sdk-workflow.*

instead as I believe this will make it possible to match other converted image
type for other kinds of builds (ePUB, PDF). Applies throughout this patch.

> +   :width: 100%
> +   :align: center
> +   :class: max-natural-size
> +
> +.. centered:: Typical ``devtool ide-sdk`` use case

You can use the :caption: option of .. image:: I believe, instead. Applies
throughout this patch.

Thanks,
Antonin