Misc doc changes (#323)

* [docs] Change CMake source flag in build documentation

From deprecated -H /path/to/source to -S /path/to/source

* [docs] Add class diagram to Simpleble 'API reference' page

Showing relationship between main frontend classes

* [docs] Add missing Cmake link

* Update api.rst

Removed class diagram. Doesn't seem necessary.

---------

Co-authored-by: Kevin Dewald <[email protected]>

docs/conf.py

@@ -36,6 +36,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    'sphinxcontrib.mermaid',
     'breathe'
 ]
 

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx==5.1.1
 sphinx_rtd_theme==1.0.0
 breathe==4.34.0
+sphinxcontrib-mermaid==0.9.2

docs/simpleble/usage.rst

@@ -58,28 +58,28 @@ Building SimpleBLE
 
 You can use the following commands to build SimpleBLE: ::
 
-   cmake -H <path-to-simpleble> -B build_simpleble
+   cmake -S <path-to-simpleble> -B build_simpleble
    cmake --build build_simpleble -j7
 
 Note that if you want to modify the build configuration, you can do so by passing
 additional arguments to the ``cmake`` command. For example, to build a shared library
 set the ``BUILD_SHARED_LIBS`` CMake variable to ``TRUE`` ::
 
-   cmake -H <path-to-simpleble> -B build_simpleble -DBUILD_SHARED_LIBS=TRUE
+   cmake -S <path-to-simpleble> -B build_simpleble -DBUILD_SHARED_LIBS=TRUE
 
 To build a plain-flavored version of the library, set the ``SIMPLEBLE_PLAIN`` CMake
 variable to ``TRUE`` ::
 
-   cmake -H <path-to-simpleble> -B build_simpleble -DSIMPLEBLE_PLAIN=TRUE
+   cmake -S <path-to-simpleble> -B build_simpleble -DSIMPLEBLE_PLAIN=TRUE
 
 To modify the log level, set the ``SIMPLEBLE_LOG_LEVEL`` CMake variable to one of the
 following values: ``VERBOSE``, ``DEBUG``, ``INFO``, ``WARN``, ``ERROR``, ``FATAL`` ::
 
-   cmake -H <path-to-simpleble> -B build_simpleble -DSIMPLEBLE_LOG_LEVEL=DEBUG
+   cmake -S <path-to-simpleble> -B build_simpleble -DSIMPLEBLE_LOG_LEVEL=DEBUG
 
 **(Linux only)** To force the usage of the DBus session bus, enable the ``SIMPLEBLE_USE_SESSION_DBUS`` flag ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez -DSIMPLEBLE_USE_SESSION_DBUS=TRUE
+   cmake -S <path-to-simplebluez> -B build_simplebluez -DSIMPLEBLE_USE_SESSION_DBUS=TRUE
 
 Installing SimpleBLE
 --------------------
@@ -182,7 +182,7 @@ Build Examples
 
 Use the following instructions to build the provided SimpleBLE examples: ::
 
-   cmake -H <path-to-simpleble>/examples/simpleble -B build_simpleble_examples -DSIMPLEBLE_LOCAL=ON
+   cmake -S <path-to-simpleble>/examples/simpleble -B build_simpleble_examples -DSIMPLEBLE_LOCAL=ON
    cmake --build build_simpleble_examples -j7
 
 
@@ -201,7 +201,7 @@ Unit Tests
 
 To run the unit tests, run the following command: ::
 
-   cmake -H <path-to-simpleble> -B build_simpleble_test -DSIMPLEBLE_TEST=ON
+   cmake -S <path-to-simpleble> -B build_simpleble_test -DSIMPLEBLE_TEST=ON
    cmake --build build_simpleble_test -j7
    ./build_simpleble_test/bin/simpleble_test
 
@@ -211,7 +211,7 @@ Address Sanitizer Tests
 
 To run the address sanitizer tests, run the following command: ::
 
-   cmake -H <path-to-simpleble> -B build_simpleble_test -DSIMPLEBLE_SANITIZE=Address -DSIMPLEBLE_TEST=ON
+   cmake -S <path-to-simpleble> -B build_simpleble_test -DSIMPLEBLE_SANITIZE=Address -DSIMPLEBLE_TEST=ON
    cmake --build build_simpleble_test -j7
    PYTHONMALLOC=malloc ./build_simpleble_test/bin/simpleble_test
 
@@ -224,7 +224,7 @@ Thread Sanitizer Tests
 
 To run the thread sanitizer tests, run the following command: ::
 
-   cmake -H <path-to-simpleble> -B build_simpleble_test -DSIMPLEBLE_SANITIZE=Thread -DSIMPLEBLE_TEST=ON
+   cmake -S <path-to-simpleble> -B build_simpleble_test -DSIMPLEBLE_SANITIZE=Thread -DSIMPLEBLE_TEST=ON
    cmake --build build_simpleble_test -j7
    ./build_simpleble_test/bin/simpleble_test
 

docs/simplebluez/usage.rst

@@ -45,23 +45,23 @@ Building SimpleBluez
 
 You can use the following commands to build SimpleBluez: ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez
+   cmake -S <path-to-simplebluez> -B build_simplebluez
    cmake --build build_simplebluez -j7
 
 Note that if you want to modify the build configuration, you can do so by passing
 additional arguments to the ``cmake`` command. For example, to build a shared library
 set the ``BUILD_SHARED_LIBS`` CMake variable to ``TRUE`` ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez -DBUILD_SHARED_LIBS=TRUE
+   cmake -S <path-to-simplebluez> -B build_simplebluez -DBUILD_SHARED_LIBS=TRUE
 
 To modify the log level, set the ``SIMPLEBLUEZ_LOG_LEVEL`` CMake variable to one of the
 following values: ``VERBOSE``, ``DEBUG``, ``INFO``, ``WARN``, ``ERROR``, ``FATAL`` ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez -DSIMPLEBLUEZ_LOG_LEVEL=DEBUG
+   cmake -S <path-to-simplebluez> -B build_simplebluez -DSIMPLEBLUEZ_LOG_LEVEL=DEBUG
 
 To force the usage of the DBus session bus, enable the ``SIMPLEBLUEZ_USE_SESSION_DBUS`` flag ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez -DSIMPLEBLUEZ_USE_SESSION_DBUS=TRUE
+   cmake -S <path-to-simplebluez> -B build_simplebluez -DSIMPLEBLUEZ_USE_SESSION_DBUS=TRUE
 
 Installing SimpleBluez
 ----------------------
@@ -161,7 +161,7 @@ Build Examples
 
 Use the following instructions to build the provided SimpleBluez examples: ::
 
-   cmake -H <path-to-simplebluez>/examples/simplebluez -B build_simplebluez_examples -DSIMPLEBLUEZ_LOCAL=ON
+   cmake -S <path-to-simplebluez>/examples/simplebluez -B build_simplebluez_examples -DSIMPLEBLUEZ_LOCAL=ON
    cmake --build build_simplebluez_examples -j7
 
 
@@ -180,7 +180,7 @@ Unit Tests
 
 To run the unit tests, run the following command: ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez_test -DSIMPLEBLUEZ_TEST=ON
+   cmake -S <path-to-simplebluez> -B build_simplebluez_test -DSIMPLEBLUEZ_TEST=ON
    cmake --build build_simplebluez_test -j7
    ./build_simplebluez_test/bin/simplebluez_test
 
@@ -190,7 +190,7 @@ Address Sanitizer Tests
 
 To run the address sanitizer tests, run the following command: ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez_test -DSIMPLEBLUEZ_SANITIZE=Address -DSIMPLEBLUEZ_TEST=ON
+   cmake -S <path-to-simplebluez> -B build_simplebluez_test -DSIMPLEBLUEZ_SANITIZE=Address -DSIMPLEBLUEZ_TEST=ON
    cmake --build build_simplebluez_test -j7
    PYTHONMALLOC=malloc ./build_simplebluez_test/bin/simplebluez_test
 
@@ -203,13 +203,15 @@ Thread Sanitizer Tests
 
 To run the thread sanitizer tests, run the following command: ::
 
-   cmake -H <path-to-simplebluez> -B build_simplebluez_test -DSIMPLEBLUEZ_SANITIZE=Thread -DSIMPLEBLUEZ_TEST=ON
+   cmake -S <path-to-simplebluez> -B build_simplebluez_test -DSIMPLEBLUEZ_SANITIZE=Thread -DSIMPLEBLUEZ_TEST=ON
    cmake --build build_simplebluez_test -j7
    ./build_simplebluez_test/bin/simplebluez_test
 
 
 .. Links
 
+.. _CMake: https://cmake.org/
+
 .. _cmake-init-fetchcontent: https://github.com/friendlyanon/cmake-init-fetchcontent
 
 .. _fmtlib: https://github.com/fmtlib/fmt

docs/simpledbus/usage.rst

@@ -45,23 +45,23 @@ Building SimpleDBus
 
 You can use the following commands to build SimpleDBus: ::
 
-   cmake -H <path-to-simpledbus> -B build_simpledbus
+   cmake -S <path-to-simpledbus> -B build_simpledbus
    cmake --build build_simpledbus -j7
 
 Note that if you want to modify the build configuration, you can do so by passing
 additional arguments to the ``cmake`` command. For example, to build a shared library
 set the ``BUILD_SHARED_LIBS`` CMake variable to ``TRUE`` ::
 
-   cmake -H <path-to-simpledbus> -B build_simpledbus -DBUILD_SHARED_LIBS=TRUE
+   cmake -S <path-to-simpledbus> -B build_simpledbus -DBUILD_SHARED_LIBS=TRUE
 
 To modify the log level, set the ``SIMPLEDBUS_LOG_LEVEL`` CMake variable to one of the
 following values: ``VERBOSE``, ``DEBUG``, ``INFO``, ``WARN``, ``ERROR``, ``FATAL`` ::
 
-   cmake -H <path-to-simpledbus> -B build_simpledbus -DSIMPLEDBUS_LOG_LEVEL=DEBUG
+   cmake -S <path-to-simpledbus> -B build_simpledbus -DSIMPLEDBUS_LOG_LEVEL=DEBUG
 
 To force the usage of the DBus session bus, enable the ``SIMPLEDBUS_USE_SESSION_DBUS`` flag ::
 
-   cmake -H <path-to-simpledbus> -B build_simpledbus -DSIMPLEDBUS_USE_SESSION_DBUS=TRUE
+   cmake -S <path-to-simpledbus> -B build_simpledbus -DSIMPLEDBUS_USE_SESSION_DBUS=TRUE
 
 Installing SimpleDBus
 ----------------------
@@ -161,7 +161,7 @@ Build Examples
 
 Use the following instructions to build the provided SimpleDBus examples: ::
 
-   cmake -H <path-to-simpledbus>/examples/simpledbus -B build_simpledbus_examples -DSIMPLEDBUS_LOCAL=ON
+   cmake -S <path-to-simpledbus>/examples/simpledbus -B build_simpledbus_examples -DSIMPLEDBUS_LOCAL=ON
    cmake --build build_simpledbus_examples -j7
 
 
@@ -180,7 +180,7 @@ Unit Tests
 
 To run the unit tests, run the following command: ::
 
-   cmake -H <path-to-simpledbus> -B build_simpledbus_test -DSIMPLEDBUS_TEST=ON
+   cmake -S <path-to-simpledbus> -B build_simpledbus_test -DSIMPLEDBUS_TEST=ON
    cmake --build build_simpledbus_test -j7
    ./build_simpledbus_test/bin/simpledbus_test
 
@@ -190,7 +190,7 @@ Address Sanitizer Tests
 
 To run the address sanitizer tests, run the following command: ::
 
-   cmake -H <path-to-simpledbus> -B build_simpledbus_test -DSIMPLEDBUS_SANITIZE=Address -DSIMPLEDBUS_TEST=ON
+   cmake -S <path-to-simpledbus> -B build_simpledbus_test -DSIMPLEDBUS_SANITIZE=Address -DSIMPLEDBUS_TEST=ON
    cmake --build build_simpledbus_test -j7
    PYTHONMALLOC=malloc ./build_simpledbus_test/bin/simpledbus_test
 
@@ -203,13 +203,15 @@ Thread Sanitizer Tests
 
 To run the thread sanitizer tests, run the following command: ::
 
-   cmake -H <path-to-simpledbus> -B build_simpledbus_test -DSIMPLEDBUS_SANITIZE=Thread -DSIMPLEDBUS_TEST=ON
+   cmake -S <path-to-simpledbus> -B build_simpledbus_test -DSIMPLEDBUS_SANITIZE=Thread -DSIMPLEDBUS_TEST=ON
    cmake --build build_simpledbus_test -j7
    ./build_simpledbus_test/bin/simpledbus_test
 
 
 .. Links
 
+.. _CMake: https://cmake.org/
+
 .. _cmake-init-fetchcontent: https://github.com/friendlyanon/cmake-init-fetchcontent
 
 .. _fmtlib: https://github.com/fmtlib/fmt