Replace Some Diagrams with Svgbob Ones

iguessthislldo · Apr 15, 2024 · b3a8d47 · b3a8d47
1 parent e8ee1db
commit b3a8d47
Show file tree

Hide file tree

Showing 10 changed files with 118 additions and 10 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -114,6 +114,7 @@ def setup(app):
     'sphinx_copybutton',
     'sphinx_markdown_builder',
     'sphinx_inline_tabs',
+    'sphinxcontrib.svgbob'
 ]
 
 # List of patterns, relative to source directory, that match files and
@@ -174,6 +175,10 @@ def setup(app):
 
 html_static_path = ['.']
 
+html_css_files = [
+    'custom.css',
+]
+
 html_theme = 'furo'
 # See documentation for the theme here:
 #   https://pradyunsg.me/furo/

diff --git a/docs/custom.css b/docs/custom.css
@@ -0,0 +1,9 @@
+/*
+ * svgbob's outputs have fixed colors, which would be fine, but the background
+ * is transparent. This makes it impossible to see a lot or all of the diagrams
+ * in dark mode. The svgbob directive has a background-color option, but
+ * setting it doesn't seem to do anything.
+ */
+.svgbob {
+  background-color: white;
+}
diff --git a/docs/devguide/images/inforepo_discovery.png b/docs/devguide/images/inforepo_discovery.png
diff --git a/docs/devguide/images/pluggable.png b/docs/devguide/images/pluggable.png
diff --git a/docs/devguide/images/rtps_discovery.png b/docs/devguide/images/rtps_discovery.png
diff --git a/docs/devguide/images/rtps_relay.png b/docs/devguide/images/rtps_relay.png
diff --git a/docs/devguide/internet_enabled_rtps.rst b/docs/devguide/internet_enabled_rtps.rst
@@ -54,7 +54,23 @@ When a client sends an RTPS datagram to its RtpsRelay instance, the RtpsRelay in
 Clients send RTPS datagrams via unicast which is generally supported and compatible with NAT.
 The RtpsRelay can be used in lieu of or in addition to conventional RTPS discovery.
 
-.. image:: images/rtps_relay.png
+.. svgbob::
+
+  +--------------+         +--------------+
+  | "RtpsRelay"  |<------->| "RtpsRelay"  |
+  +--------------+   "3"   +--------------+
+         ^                        ^
+         | "2"                "4" |
+         V                        V
+  +--------------+         +--------------+
+  |  "Firewall"  |         |  "Firewall"  |
+  +--------------+         +--------------+
+         ^                        ^
+         | "1"                "5" |
+         V                        V
+  +--------------+         +--------------+
+  |"Pariticpant" |         |"Pariticpant" |
+  +--------------+         +--------------+
 
 The preceding diagram illustrates how the RtpsRelay can be used to connect participants that are behind firewalls that may be performing NAT.
 First, a Participant sends an RTPS datagram to its associated RtpsRelay (1).

diff --git a/docs/devguide/introduction.rst b/docs/devguide/introduction.rst
@@ -380,7 +380,25 @@ Transmission of :term:`samples <Sample>` and information related to their manage
 Transports are typically specified via configuration files and are attached to various entities in the publisher and subscriber processes.
 See :ref:`config-transport` for details on configuring transports generally.
 
-.. figure:: images/pluggable.png
+.. svgbob::
+
+  .---------------------------.  .---------------------------.
+  |  "Publisher Application"  |  |  "Subscriber Application" |
+  | +-----------------------+ |  | +-----------------------+ |
+  | |      "DataWriter"     | |  | |      "DataReader"     | |
+  | +-----------------------+ |  | +-----------------------+ |
+  | |      "Publisher"      | |  | |      "Subscriber"     | |
+  | +-----------------------+ |  | +-----------------------+ |
+  | |  "DomainParticipant"  | |  | |  "DomainParticipant"  | |
+  | +-----------+-----------+ |  | +-----------+-----------+ |
+  | |"Discovery"|"Transport"| |  | |"Transport"|"Discovery"| |
+  | +-----o-----+-----o-----+ |  | +-----o-----+-----o-----+ |
+  |       |           |       |  |       |           |       |
+  |       +-----+-----+       |  |       +-----+-----+       |
+  `-------------|-------------'  `-------------|-------------'
+                |                              |
+                |           "Network"          |
+  ==============#==============================#==============
 
 Transports are used along with :ref:`discovery <discovery>` to define how OpenDDS communicates.
 
@@ -558,9 +576,28 @@ Each OpenDDS application connects to the DCPSInfoRepo and creates records for it
 As records for data writers and data readers are created, they are matched against the existing set of records.
 When matches are found, the DCPSInfoRepo invokes the participant to perform the necessary associations.
 
-.. figure:: images/inforepo_discovery.png
-
-   Centralized Discovery with DCPSInfoRepo
+.. svgbob::
+
+          .---------------------------.  .---------------------------.
+          |  "Publisher Application"  |  |  "Subscriber Application" |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |      "DataWriter"     | |  | |      "DataReader"     | |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |      "Publisher"      | |  | |      "Subscriber"     | |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |  "DomainParticipant"  | |  | |  "DomainParticipant"  | |
+          | +-----------+-----------+ |  | +-----------+-----------+ |
+          | |"InfoRepo" |"Transport"| |  | |"Transport"|"InfoRepo" | |
+          | |"Discovery"|           | |  | |           |"Discovery"| |
+          | +-----o-----+-----o-----+ |  | +-----------+-----------+ |
+          |       |           |       |  |       ^           ^       |
+          `-------|-----------|-------'  `-------|-----------|-------'
+                  |           +------------------+           |
+  "1. Publisher"  |       "3. Publisher Writes Samples"      |2. Subscriber
+  "   Advertises" |                                          |   Discovers
+  "   Topic"      |        .------------------------.        |   Topic
+                  +------->+ "InfoRepo Application" +--------+
+                           `------------------------'
 
 .. important::
 
@@ -599,12 +636,31 @@ RTPS Discovery
 ..
     Sect<1.2.3.3.2>
 
-RTPS discovery is a peer-to-peer discovery mechanism standardized as part of the :omgspec:`RTPS spec <rtps:8.5 Discovery Module>`
+RTPS discovery is a peer-to-peer discovery mechanism standardized as part of the :omgspec:`RTPS spec <rtps:8.5 Discovery Module>`.
 Other DDS implementations can interoperate with OpenDDS when RTPS discovery is used with the :ref:`rtps-udp-transport`.
 
-.. figure:: images/rtps_discovery.png
-
-  Peer-to-peer Discovery with RTPS
+.. svgbob::
+
+          .---------------------------.  .---------------------------.
+          |  "Publisher Application"  |  |  "Subscriber Application" |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |      "DataWriter"     | |  | |      "DataReader"     | |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |      "Publisher"      | |  | |      "Subscriber"     | |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |  "DomainParticipant"  | |  | |  "DomainParticipant"  | |
+          | +-----------+-----------+ |  | +-----------+-----------+ |
+          | |"RTPS"     |"Transport"| |  | |"Transport"|"RTPS"     | |
+          | |"Discovery"|           | |  | |           |"Discovery"| |
+          | +-----o-----+-----o-----+ |  | +-----------+-----------+ |
+          |       |           |       |  |       ^           ^       |
+          `-------|-----------|-------'  `-------|-----------|-------'
+                  |           +------------------+           |
+  "1. Publisher"  |       "3. Publisher Writes Samples"      |2. Subscriber
+  "   Advertises" |                                          |   Discovers
+  "   Topic"      |                                          |   Topic
+                  |         "RTPS SPDP Multicast Group"      |
+          ========#==========================================#========
 
 .. important::
 
@@ -653,6 +709,27 @@ Static Discovery
 
 In Static Discovery, each participant starts with a database containing identifiers, QoS settings, and network locators for all participants, topics, data writers, data readers.
 
+.. svgbob::
+
+          .---------------------------.  .---------------------------.
+          |  "Publisher Application"  |  |  "Subscriber Application" |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |      "DataWriter"     | |  | |      "DataReader"     | |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |      "Publisher"      | |  | |      "Subscriber"     | |
+          | +-----------------------+ |  | +-----------------------+ |
+          | |  "DomainParticipant"  | |  | |  "DomainParticipant"  | |
+          | +-----------+-----------+ |  | +-----------+-----------+ |
+          | |"Static"   |"RTPS UDP" | |  | |"RTPS UDP" |"Static"   | |
+          | |"Discovery"|"Transport"| |  | |"Transport"|"Discovery"| |
+          | +-----------+-----o-----+ |  | +-----------+-----------+ |
+          |                   |       |  |       ^                   |
+          `-------------------|-------'  `-------|-------------------'
+                              +------------------+
+                          "2. Publisher Writes Samples"
+                                                        1. Subscriber
+                                                           Assumes Topic
+
 .. important::
 
   The :ref:`rtps-udp-transport` is the only transport that can be used with Static Discovery.

diff --git a/docs/devguide/introduction_to_dds.rst b/docs/devguide/introduction_to_dds.rst
@@ -46,7 +46,7 @@ Domain
 The *domain* is the fundamental partitioning unit within DCPS.
 Each of the other entities belongs to a domain and can only interact with other entities in that same domain.
 Application code is free to interact with multiple domains but must do so via separate entities that belong to the different domains.
-Domains are identified by an identifier.
+Domains are identified by an integer identifier.
 There is no entity in the DCPS API that represents the domain.
 
 Entity

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -6,3 +6,4 @@ sphinx-copybutton
 sphinx-markdown-builder @ git+https://github.com/liran-funaro/sphinx-markdown-builder
 sphinx-inline-tabs
 PyMuPDF
+sphinxcontrib-svgbob