[#1390] Improve plugins documentation

Author: ReeceHumphreys

docs/source/Plugins/overview.rst

@@ -94,24 +94,24 @@ Basilisk plugins are built with `bsk-sdk <https://pypi.org/project/bsk-sdk/>`_,
 a companion Python package that ships the headers, SWIG interface files, and
 CMake helpers needed to compile out-of-tree modules.
 
-.. code-block:: text
+.. graphviz::
+
+   digraph plugin_arch {
+      graph [rankdir=TB, splines=ortho, bgcolor=transparent, nodesep=0.5]
+      node  [shape=box, style="rounded,filled", fontname="Helvetica",
+             fontsize=13, margin="0.4,0.2", width=4, fixedsize=false]
+      edge  [fontname="Helvetica", fontsize=11, minlen=2]
+
+      plugin [label="Your plugin\n(separate repo / wheel)",
+              fillcolor="#dce8fb"]
+      sdk    [label="bsk-sdk\n(BSK headers · SWIG interfaces · CMake helpers)",
+              fillcolor="#d4edda"]
+      bsk    [label="Basilisk: pip install bsk",
+              fillcolor="#fff3cd"]
 
-    ┌─────────────────────────────────────┐
-    │  Your plugin (separate repo/wheel)  │
-    │                                     │
-    │   myModule.cpp / myModule.h         │
-    │   myModule.i                        │
-    │   CMakeLists.txt                    │
-    └──────────────┬──────────────────────┘
-                   │ links against
-    ┌──────────────▼──────────────────────┐
-    │  bsk-sdk wheel                      │
-    │  (vendored BSK headers + cmake)     │
-    └──────────────┬──────────────────────┘
-                   │ compatible with
-    ┌──────────────▼──────────────────────┐
-    │  Basilisk (pip install bsk)         │
-    └─────────────────────────────────────┘
+      plugin -> sdk [label="  compiles against  "]
+      sdk    -> bsk [label="  compatible with  "]
+   }
 
 The plugin compiles against the same BSK headers and SWIG runtime that
 Basilisk uses, so message types, base classes, and the module API are
@@ -126,19 +126,21 @@ Quick Start
 
     pip install bsk-sdk
 
-**2. Create your plugin layout** (following BSK module conventions)
+**2. Create your plugin layout**
 
 .. code-block:: text
 
     my-plugin/
     ├── pyproject.toml
     ├── CMakeLists.txt
-    └── myModule/
-        ├── myModule.h
-        ├── myModule.cpp
-        ├── myModule.i
+    ├── my_plugin/                  # importable Python package
+    │   └── __init__.py
+    └── exampleCppModule/           # C++/SWIG source
+        ├── exampleCppModule.h
+        ├── exampleCppModule.cpp
+        ├── exampleCppModule.i
         └── _UnitTest/
-            └── test_myModule.py
+            └── test_exampleCppModule.py
 
 **3. Wire up CMakeLists.txt**
 
@@ -158,10 +160,9 @@ Quick Start
     find_package(bsk-sdk CONFIG REQUIRED)
 
     bsk_add_swig_module(
-      TARGET myModule
-      INTERFACE myModule/myModule.i
-      SOURCES   myModule/myModule.cpp
-      LINK_LIBS bsk::plugin
+      TARGET exampleCppModule
+      INTERFACE exampleCppModule/exampleCppModule.i
+      SOURCES   exampleCppModule/exampleCppModule.cpp
       OUTPUT_DIR "${SKBUILD_PLATLIB_DIR}/my_plugin"
     )
 
@@ -177,11 +178,11 @@ Quick Start
 
 .. code-block:: python
 
-    from my_plugin import myModule
+    from my_plugin import exampleCppModule
     from Basilisk.utilities import SimulationBaseClass
 
     sim = SimulationBaseClass.SimBaseClass()
-    mod = myModule.MyModule()
+    mod = exampleCppModule.ExampleCppModule()
     sim.AddModelToTask("task", mod)
 
 A complete working example is provided in the

docs/source/Plugins/writing.rst

@@ -30,22 +30,29 @@ Prerequisites
 Plugin Layout
 -------------
 
-Follow the same folder convention as BSK — one folder per module, named
-identically to the module:
+Every plugin needs a Python package directory (``my_plugin/`` below). This
+is the importable namespace your users will ``import`` from, and where both
+compiled SWIG extensions and pure-Python modules are installed.  C++/SWIG
+source trees live alongside it at the repo root and get compiled into that
+package at build time.  Pure-Python modules can be added directly inside the
+package directory with no extra build steps:
 
 .. code-block:: text
 
     my-plugin/
     ├── pyproject.toml
     ├── CMakeLists.txt
-    ├── messages/               # (optional) custom message definitions
+    ├── my_plugin/                      # Python package (SWIG outputs install here too)
+    │   ├── __init__.py
+    │   └── examplePythonModule.py      # (optional) pure-Python modules
+    ├── messages/                       # (optional) custom message definitions
     │   └── MyMsgPayload.h
-    └── myModule/
-        ├── myModule.h
-        ├── myModule.cpp
-        ├── myModule.i
+    └── exampleCppModule/               # C++/SWIG module source
+        ├── exampleCppModule.h
+        ├── exampleCppModule.cpp
+        ├── exampleCppModule.i
         └── _UnitTest/
-            └── test_myModule.py
+            └── test_exampleCppModule.py
 
 SWIG Interface
 --------------
@@ -55,14 +62,14 @@ The ``.i`` file is the same as any BSK module.  For C++ use
 
 .. code-block:: swig
 
-    %module myModule
+    %module exampleCppModule
     %{
-    #include "myModule.h"
+    #include "exampleCppModule.h"
     %}
 
     %include "swig_common_model.i"   /* C++ modules */
     /* %include "swig_c_wrap.i"      C modules — use %c_wrap_2 instead */
-    %include "myModule.h"
+    %include "exampleCppModule.h"
 
 If subclassing a BSK base class, ``%include`` its ``.i`` file before yours:
 
@@ -107,24 +114,22 @@ plugin-specific section:
     # Plugin-specific configuration
     # ==========================================================================
 
-    file(GLOB PLUGIN_SOURCES CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/myModule/*.cpp")
+    file(GLOB PLUGIN_SOURCES CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/exampleCppModule/*.cpp")
 
     # If subclassing a BSK base class (AtmosphereBase, DynamicEffector, etc.),
-    # add its implementation from the SDK:
-    # list(APPEND PLUGIN_SOURCES "${BSK_SDK_RUNTIME_MIN_DIR}/atmosphereBase.cpp")
-
+    # bsk_add_swig_module automatically links the required SDK runtime sources —
+    # no manual list(APPEND) is needed.  See the `custom-atm-plugin` example.
     bsk_add_swig_module(
-      TARGET myModule
-      INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/myModule/myModule.i"
+      TARGET exampleCppModule
+      INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/exampleCppModule/exampleCppModule.i"
       SOURCES   ${PLUGIN_SOURCES}
       INCLUDE_DIRS
-        "${CMAKE_CURRENT_SOURCE_DIR}/myModule"
+        "${CMAKE_CURRENT_SOURCE_DIR}/exampleCppModule"
         "${CMAKE_CURRENT_SOURCE_DIR}/messages"
-      LINK_LIBS bsk::plugin
       OUTPUT_DIR "${PKG_DIR}"
     )
 
-    # Optional: generate Python bindings for custom messages
+    # Optionally generate Python bindings for custom messages
     bsk_generate_messages(
       OUTPUT_DIR "${PKG_DIR}/messaging"
       MSG_HEADERS
@@ -137,17 +142,24 @@ pyproject.toml
 .. code-block:: toml
 
     [build-system]
-    requires = ["scikit-build-core>=0.9"]
+    requires = ["scikit-build-core>=0.9.3", "bsk-sdk==2.X.Y", "bsk==2.X.Y", "swig==4.4.1"]
     build-backend = "scikit_build_core.build"
 
     [project]
     name = "my-plugin"
     version = "1.0.0"
     requires-python = ">=3.9"
-    dependencies = ["bsk"]
+    dependencies = ["bsk==2.X.Y"]
 
     [tool.scikit-build]
-    wheel.packages = []
+    wheel.packages = ["my_plugin"]
+
+.. note::
+
+   ``bsk-sdk``, ``bsk``, and the runtime ``dependencies`` entry must all be
+   **pinned to the same version**.  The SDK compiles BSK sources into your
+   plugin at build time, so mismatched versions will produce a CMake error.
+   Replace ``2.X.Y`` with the Basilisk version you are targeting.
 
 Building and Installing
 -----------------------
@@ -162,7 +174,7 @@ Building and Installing
     pip install dist/*.whl
 
     # Run unit tests
-    pytest myModule/_UnitTest/ -v
+    pytest exampleCppModule/_UnitTest/ -v
 
 Publishing to PyPI
 ------------------