Adding the diagram to the generated files

canonical · Oct 3, 2023 · c14787e · c14787e
1 parent 7a67e9e
commit c14787e
Show file tree

Hide file tree

Showing 7 changed files with 39 additions and 37 deletions.
diff --git a/doc/sphinx/.sphinx/requirements.txt b/doc/sphinx/.sphinx/requirements.txt
@@ -13,3 +13,4 @@ sphinxcontrib-jquery
 sphinx-notfound-page
 breathe
 exhale
+sphinxcontrib-mermaid
diff --git a/doc/sphinx/architecture.md b/doc/sphinx/architecture.md
@@ -1,31 +1,31 @@
-# Overview
+# Architecture
 This document describes the high-level architecture of *Mir*, including a diagram and a brief introduction of the libraries.
 
-# Audience
+## Audience
 This document is intended to provide contributors to *Mir* an overview of *Mir*'s systems. It is *not* intended to guide compositor-implementers, unless they are specifically interested in the internals of *Mir*.
 
-# Diagram
-![Architecture Diagram](./architecture.png "Architecture Diagram")
+## Diagram
+[Architecture Diagram](./architecture_diagram.rst)
 
-# Top-Level Folders
-## `/include`
+## Top-Level Folders
+### `/include`
 - The `include` folder at the root of the project provides the public-facing API.
 - This directory *strictly* includes the interfaces that are useful to a compositor-implementer.
 - If one is only interested in implementing their own *Mir*-based compositor, they need not look any further than this directory.
 
-## `/src`
+### `/src`
 - The `src` folder at the root of the project comprises the core implementation of *Mir*.
 
-## `/examples`
+### `/examples`
 - A collection of demo *Mir* compositors that are used as examples of how one might build a true compositor. Examples include:
   - `miral-app`
   - `miral-shell`
   - `mir_demo_server`
 
-## `/tests`
+### `/tests`
 - Tests for the project, including unit tests, integration tests, acceptance tests, and test framework.
 
-# Libraries
+## Libraries
 The following is the library tree:
 ```
 ├── miral
@@ -54,28 +54,28 @@ The following is the library tree:
 └──  mirwayland
 ```
 
-## miral
+### miral
 - The "Mir Abstraction Layer" (aka `MirAL` or `miral`) is an API that makes Mir easy for compositor-implementers to work with. It provides the core window management concepts and an interface that is more ABI stable than Mir's internal mirserver API.
 - Public-facing
 - Directories:
   - `include/miral`
   - `src/miral`
 
-## miroil
+### miroil
 - A custom *Mir* library for the [Lomiri](https://lomiri.com/) folks
 - This is unimportant for 99% of people
 - Directories:
   - `include/miroil`
   - `src/miroil`
 
-## mircore
+### mircore
 - Fundamental data structures like 2D points, Rectangles, File Descriptor, etc.
 - Public-facing
 - Directories:
   - `include/core`
   - `src/core`
   -
-## mircommon
+### mircommon
 - Data structures and utility functions like Mir-event building, logging, keymaps, etc.
 - Differs from `mircore` in that the concepts map strictly onto *Mir*'s concepts instead of being general concepts like a Rectangle
 - Public-facing
@@ -84,15 +84,15 @@ The following is the library tree:
   - `src/common`
   - `src/include/common`
 
-## mircookie
+### mircookie
 - Provides event timestamps for inputs events that are difficult to spoof.
 - Public-facing
 - Directories:
   - `include/cookie`
   - `src/cookie`
   - `src/include/cookie`
 
-## mirserver
+### mirserver
 - Provides the core *Mir* runtime, with the entry-point being the `mir::Server` class.
 - The `Server` class has a `DisplayServer` which provides access to the interfaces that that support the server's runtime.
   - The `ServerConfiguration` provides a bunch of methods called `the_XYZ()` to access these various instances, where "XYZ" can be replaced with the interface of interest.
@@ -102,14 +102,14 @@ The following is the library tree:
   - `src/server`
   - `src/include/server`
 
-## mircompositor
+### mircompositor
 - Included in `mirserver.so`
 - The `Compositor` is responsible for collecting the set of renderables and sending them off to the outputs to be displayed.
 - Directories:
   - `src/include/server/mir/compositor`
   - `src/server/compositor`
 
-## mirinput
+### mirinput
 - Included in `mirserver.so`
 - Deals with everything input (e.g. keyboard presses, mouse clicks)
 - The `InputManager` provides access to the specific input platform that is running (e.g. X, Wayland, or libinput).
@@ -118,33 +118,33 @@ The following is the library tree:
   - `src/include/server/mir/input`
   - `src/server/input`
 
-## mirfrontend-wayland
+### mirfrontend-wayland
 - The *Mir* implementation of the wayland protocol.
 - The `WaylandConnector` class is the glue between the compositor and the specific details of the wayland protocol.
 - Directories:
   - `src/server/frontend_wayland`
 
-## mirfrontend-xwayland
+### mirfrontend-xwayland
 - The *Mir* implementation of the xwayland protocol.
 - The `XWaylandConnector` class is the glue between the compositor and the specific details of the xwayland protocol.
 - This protocol talks to the `xwayland` server, which is spawned as a subprocess.
 - Directories:
   - `src/server/frontend_xwayland`
 
-## mirshell
+### mirshell
 - The `Shell` is responsible for managing the surfaces that the compositor wants to show.
 - It provides an interface to create, update, and remove these surfaces from the display.
 - As an example, the `WaylandConnector` might ask the `Shell` to create a new surface for it.
 - Directories:
   - `src/include/server/mir/shell`
   - `src/server/shell`
 
-## mirshelldecoration
+### mirshelldecoration
 - Manages *Mir*'s server-side decoration of windows. Currently only used for X11 clients.
 - Directories:
   - `src/server/shell/decoration`
 
-## mirscene
+### mirscene
 - The `Scene` provides an interface for the `Compositor` to access the list of renderable items
   - These renderables are derived from the surfaces that were added to the `Shell`.
   - You can think of the `Scene` as you would think of a "scene graph" in a 3D game engine.
@@ -153,45 +153,45 @@ The following is the library tree:
   - `src/include/mir/server/scene`
   - `src/server/scene`
 
-## mirgraphics
+### mirgraphics
 - A graphics abstraction layer sitting between the compositor and the specific graphics platform that it is using to render.
 - Directories:
   - `src/include/mir/server/graphics`
   - `src/server/graphics`
 
-## mirreport
+### mirreport
 - Default logging and reporting facilities
 - Directories:
   - `src/server/report`
 
-## mirconsole
+### mirconsole
 - Handles `logind` and virtual-terminal related tasks for the compositor
 - Directories:
   - `src/server/console`
 
-## mirgl
+### mirgl
 - A short list of helpers for GL things
 - Directories:
   - `src/gl`
 
-## mirrenderergl
+### mirrenderergl
 - The only supported `Renderer` type for now
 - Future renderers will be found alongside it in the `src/renderers` directory
 - Directories:
   - `src/renderers/gl`
 
-## mirplatform
+### mirplatform
 - Graphics and input code that is shared between the platforms found in `src/platforms`
 - Directories
   - `src/include/platform`
   - `src/platform`
 
-## mirwayland
+### mirwayland
 - A subproject used to generate C++ classes from wayland protocol XML files.
 - Directories:
   - `src/wayland`
 
-## platforms (the directory, not a namespace)
+### platforms (the directory, not a namespace)
 - A **platform** is a backend that the compositor selects at runtime
 - There are three distinct platforms that the compositor makes use of:
   - *DisplayPlatform*: determines what the compositor is rendering *to* (e.g gbm-kms, x11, wayland)

diff --git a/doc/sphinx/architecture_diagram.rst b/doc/sphinx/architecture_diagram.rst
@@ -0,0 +1,4 @@
+Architecture Diagram
+--------------
+
+.. mermaid:: ./high_level_diagram.mmd
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
@@ -17,7 +17,6 @@
 
 extensions = [
     'sphinx_design',
-    'sphinx_tabs.tabs',
     'sphinx_reredirects',
     'youtube-links',
     'related-links',

diff --git a/doc/sphinx/custom_conf.py.in b/doc/sphinx/custom_conf.py.in
@@ -114,6 +114,7 @@ custom_extensions = [
     'breathe',
     'exhale',
     'sphinx.ext.graphviz',
+    'sphinxcontrib.mermaid'
 ]
 
 # Add files or directories that should be excluded from processing.

diff --git a/doc/sphinx/architecture.mermaid → doc/sphinx/high_level_diagram.mmd b/doc/sphinx/architecture.mermaid → doc/sphinx/high_level_diagram.mmd
@@ -30,10 +30,6 @@ classDiagram
         class X11DisplayPlatform
         class WaylandDisplayPlatform
     }
-    <<abstract>> DisplayPlatform
-    <<abstract>> Display
-    <<abstract>> DisplayBuffer
-
     ServerConfiguration *-- DisplayPlatform
     ServerConfiguration *-- MultiplexingDisplay
     DisplayPlatform *-- Display
@@ -129,7 +125,6 @@ classDiagram
         class Renderer
         class GlRenderer
     }
-    <<abstract>> Renderer
     DefaultDisplayBufferCompositorFactory *-- RendererFactory
     RendererFactory <-- Renderer
     Renderer <|-- GlRenderer
diff --git a/doc/sphinx/index.md b/doc/sphinx/index.md
@@ -31,5 +31,7 @@ The server API is introduced here: [Introducing the MirAL API](introducing_the_m
 
 getting_and_using_mir
 getting_involved_in_mir
+architecture
+architecture_diagram
 api/library_root
 ```