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. --- docs/conf.py | 22 +++++++++++++++ docs/devel/index-process.rst | 47 +++++++++++++++++++++++++++++++++ docs/meson.build | 3 ++- docs/requirements.txt | 1 + configure | 6 +++++ pythondeps.toml | 1 + tests/lcitool/mappings.yml | 3 +++ tests/lcitool/projects/qemu.yml | 1 + 8 files changed, 83 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 914bae67d9c..9fc7be362ba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,8 +66,11 @@ 'qapi_domain', 'qapidoc', 'qmp_lexer', + 'sphinxcontrib.plantuml', ] +plantuml_output_format = 'svg' + # Add any paths that contain templates here, relative to this directory. templates_path = [os.path.join(qemu_docdir, '_templates')] @@ -345,3 +348,22 @@ qapidoc_srctree = os.path.join(qemu_docdir, '..') dbusdoc_srctree = os.path.join(qemu_docdir, '..') dbus_index_common_prefix = ["org.qemu."] + + +def setup(app): + import docutils.nodes + import sphinxcontrib.plantuml + + # We manually setup the plantuml extension so we can skip nodes with + # diagrams when generating the text based output. + + def skip_node(self, node): + raise docutils.nodes.SkipNode + + app.setup_extension('sphinxcontrib.plantuml') + app.add_node( + sphinxcontrib.plantuml.plantuml, + override=True, + man=(skip_node, None), + text=(skip_node, None), + ) diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst index ce0f4e73197..1c13dd3f7b5 100644 --- a/docs/devel/index-process.rst +++ b/docs/devel/index-process.rst @@ -5,6 +5,53 @@ QEMU Community Processes Notes about how to interact with the community and how and where to submit patches. +.. uml:: + :caption: QEMU Patch Review and Acceptance Flow + + @startuml + skinparam roundCorner 8 + skinparam shadowing false + skinparam defaultFontName monospace + skinparam sequenceMessageAlign center + + actor "Developer" as dev + participant "QEMU Community\n(qemu-devel)" as list + actor "Subsystem\nMaintainer" as sub + actor "QEMU\nMaintainer" as top + + dev -> dev: Develop & test feature + + loop Needs revision (v1, v2, ... vn) + dev -> list: Post patch series to list + note over list: Code review on list + + opt Review comments + list -> dev: Feedback & change requests + dev -> dev: Incorporate feedback + end + opt Review tags + list -> dev: Tags (Reviewed-by, Acked-by, ...) + dev -> dev: Apply tags + end + + dev -> dev: Prepare n+1 + end + + group Patch acceptance & release + list -> sub: Maintainer accepts some or all patches + note over sub: Incorporates patches\nfrom other developers + sub -> sub: Add Maintainer Sign-off + sub -> sub: GIT branch foo/next + sub -> list: Sign & Submit Pull Request + list -> top: Pull Request delivered to list + note over top: Pull Requests from\nother maintainers + top -> top: Test and Merge Pull Reqs + top -> top: qemu.git master + top -> top: Tag Release + top -> list: QEMU Release + end + @enduml + .. toctree:: :maxdepth: 2 diff --git a/docs/meson.build b/docs/meson.build index 4d8cc545fcc..600d3283299 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,9 +1,10 @@ sphinx_build = find_program(fs.parent(python.full_path()) / 'sphinx-build', required: get_option('docs')) +plantuml = find_program('plantuml', required: get_option('docs')) # Check if tools are available to build documentation. build_docs = false -if sphinx_build.found() +if sphinx_build.found() and plantuml.found() SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q'] # If we're making warnings fatal, apply this to Sphinx runs as well if get_option('werror') diff --git a/docs/requirements.txt b/docs/requirements.txt index 509d56bd1e8..1cafcbaa38f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,4 @@ sphinx==7.2.6 sphinx_rtd_theme==2.0.0 +sphinxcontrib-plantuml==0.30 diff --git a/configure b/configure index 42dffed28f0..b0dedde65dd 100755 --- a/configure +++ b/configure @@ -1020,6 +1020,12 @@ if test "$docs" != "disabled" ; then fi echo "Sphinx not found/usable, disabling docs." docs=disabled + elif ! has plantuml; then + if test "$docs" = "enabled" ; then + error_exit "plantuml not found" + fi + echo "plantuml not found, disabling docs." + docs=disabled else docs=enabled fi diff --git a/pythondeps.toml b/pythondeps.toml index c9a697046c6..c21d127ec93 100644 --- a/pythondeps.toml +++ b/pythondeps.toml @@ -30,6 +30,7 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" } # Please keep the installed versions in sync with docs/requirements.txt sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" } sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "2.0.0" } +sphinxcontrib-plantuml = { accepted = ">=0.5", installed = "0.30" } # This test group is for dependencies required to run various tooling # and tests that should always be installed at configure time. It should diff --git a/tests/lcitool/mappings.yml b/tests/lcitool/mappings.yml index c99f007798e..eca6748ac09 100644 --- a/tests/lcitool/mappings.yml +++ b/tests/lcitool/mappings.yml @@ -3,6 +3,9 @@ mappings: bindgen: Ubuntu2204: + plantuml: + default: plantuml + python3: CentOSStream9: python3.12 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 -- 2.47.3
