diff --git a/doc/sphinx/.sphinx/requirements.txt b/doc/sphinx/.sphinx/requirements.txt index 9ae1d947e69..a891699b360 100644 --- 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 index 8aece1af9d3..8a3fab50ce4 100644 --- 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,7 +84,7 @@ 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: @@ -92,7 +92,7 @@ The following is the library tree: - `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,20 +118,20 @@ 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. @@ -139,12 +139,12 @@ The following is the library tree: - `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 new file mode 100644 index 00000000000..b4b9582a1b1 --- /dev/null +++ b/doc/sphinx/architecture_diagram.rst @@ -0,0 +1,4 @@ +Architecture Diagram +-------------- + +.. mermaid:: ./high_level_diagram.mmd \ No newline at end of file diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index fa20cf163f2..d2b247a143f 100644 --- 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 index 661a09b9efb..4632812daba 100644 --- 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 b/doc/sphinx/high_level_diagram.mmd similarity index 96% rename from doc/sphinx/architecture.mermaid rename to doc/sphinx/high_level_diagram.mmd index c4b99a66cfd..aa0132cb759 100644 --- a/doc/sphinx/architecture.mermaid +++ b/doc/sphinx/high_level_diagram.mmd @@ -30,10 +30,6 @@ classDiagram class X11DisplayPlatform class WaylandDisplayPlatform } - <> DisplayPlatform - <> Display - <> DisplayBuffer - ServerConfiguration *-- DisplayPlatform ServerConfiguration *-- MultiplexingDisplay DisplayPlatform *-- Display @@ -129,7 +125,6 @@ classDiagram class Renderer class GlRenderer } - <> Renderer DefaultDisplayBufferCompositorFactory *-- RendererFactory RendererFactory <-- Renderer Renderer <|-- GlRenderer \ No newline at end of file diff --git a/doc/sphinx/index.md b/doc/sphinx/index.md index 6d960f73882..84e1ddb3377 100644 --- 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 ```