[sdk/codevis] doc/xml-docbook: Add plugins docbook entries (Plugin documentation file)

[Tarcisio Fischer]

Git commit 1ee9ec7350aaae847c409050805e1aa0623d4404 by Tarcisio Fischer.
Committed on 19/10/2023 at 14:21.
Pushed by tcanabrava into branch 'master'.

Add plugins docbook entries (Plugin documentation file)

Signed-off-by: Tarcisio Fischer <tarcisio.fischer at codethink.co.uk>

M  +107  -2    doc/xml-docbook/man-codevis_desktop.1.docbook

https://invent.kde.org/sdk/codevis/-/commit/1ee9ec7350aaae847c409050805e1aa0623d4404

diff --git a/doc/xml-docbook/man-codevis_desktop.1.docbook b/doc/xml-docbook/man-codevis_desktop.1.docbook
index 7d22b78..50db80c 100644
--- a/doc/xml-docbook/man-codevis_desktop.1.docbook
+++ b/doc/xml-docbook/man-codevis_desktop.1.docbook
@@ -14,6 +14,8 @@
     <title>&codevis; User's Manual</title>
     <author>&Tomaz.Canabrava; &Tomaz.Canabrava.mail;</author>
     <date>2024-00-00</date>
+    <author>&Tarcisio.Fischer; &Tarcisio.Fischer.mail;</author>
+    <date>2023-10-19</date>
     <releaseinfo>KDE Gear 24.00</releaseinfo>
     <productname>KDE Gear</productname>
 </refentryinfo>
@@ -42,7 +44,7 @@
 <para>
   Some of &codevis;'s many features includes software architecture visualization,
   manipulation, code generation from diagrams, diagrams generation from source code,
-  plugins, static analysis, visual static analysis and much more. 
+  plugins, static analysis, visual static analysis and much more.
 </para>
 
 <para>
@@ -51,7 +53,6 @@
   and experimenting. Many architectural issues were found and fixed on &codevis; itself by
   analyzing it's source code.
 </para>
-
 </refsect1>
 
 <refsect1>
@@ -65,6 +66,110 @@
     </variablelist>
 </refsect1>
 
+<refsect1>
+<title>Plugins</title>
+<para>
+Codevis application supports plugins. It is possible to create plugins in C++, Python or mix the two languages.
+</para>
+<para>
+The plugin system works as follows: There's a set of places in the application code that call user-definable functions.
+ Those functions are called "Hooks". Each hook receives a pointer to a "handler" that'll be provided by the application.
+ So a "hook" is a "place" _where_ the function will be called and the handler is _what_ can be called back to change
+ application behavior.
+</para>
+<para>
+All hooks are defined in the [hooks.py](../lvtplg/hooks.py) file. All handlers are defined in one of the handler files
+in the [handlers.py](../lvtplg/handlers.py) file. Handlers may return application data structures, such as an "Entity".
+Those are available in the [plugin data types file](../lvtplg/ct_lvtplg_plugindatatypes.h).
+</para>
+<para>
+In order for the application to recognize the plugins, they need to be in a specific place and they need to have a
+specific set of files. This is the file structure each plugin must have:
+</para>
+<para>
+$plugin_name/
++ $plugin_name.[py|so]
++ metadata.json
++ README.md
+</para>
+<para>
+Where `$plugin_name` is the plugin's name. `metadata.json` file follows the [kcoreaddons](https://api.kde.org/frameworks/kcoreaddons/html/)
+specification (There's an example below). And the `README.md` file should contain a brief description, and
+possibly examples on how to use the plugin.
+</para>
+<para>
+The `$plugin_name` folder must be copied to one of those paths, so that the application can find the plugin:
+</para>
+<para>
+- `$user_home/lks-plugins/` (Preferred for local development)
+- `$app_installation_path/lks-plugins/` (Used for plugins that are bundled with the app)
+- `$app_local_data/plugins/` (Used for downloaded plugins)
+</para>
+<para>
+There are a few working examples in the [plugins folder](../plugins/). There's also some [plugins for integration test](../lvtplg/testplugins/)
+that may be useful as simple examples. But just to give the
+reader a more step-by-step explanation, this section will show a working plugin written in Python.
+There's also a [python template plugin](../plugins/python_template_plugin/) that may be used as starting point.
+</para>
+<para>
+**Step 1**: Create the following folder structure inside `$user_home/lks-plugins/` (example: `/home/tarcisio/lks-plugins/`):
+</para>
+<para>
+```
+myfirstplugin/
++ myfirstplugin.py
++ metadata.json
++ README.md
+```
+</para>
+<para>
+**Step 2**: Populate the `metadata.json` file with the following contents:
+</para>
+<para>
+```
+ {
+  "KPlugin": {
+     "Name": "My first plugin",
+     "Description": "Example plugin",
+     "Icon": "none",
+     "Authors": [ { "Name": "YourName", "Email": "YourEmail" } ],
+     "Category": "Codevis Plugins",
+     "EnabledByDefault": true,
+     "License": "YourLicense",
+     "Id": "myfirstplugin",
+     "Version": "0.1",
+     "Website": "YourPluginWebsite"
+  }
+}
+```
+</para>
+<para>
+**Step 3**: Populate the `myfirstplugin.py` file with the actual plugin code:
+</para>
+<para>
+```python
+import pyLksPlugin as plg # Contains Codevis data structures
+
+def hookSetupPlugin(handler):
+    # This will be executed once when the application starts
+    print("Hello world from Python plugin!")
+
+
+def hookTeardownPlugin(handler):
+    # This will be executed once when the application closes
+    print("Okay then. Bye!")
+```
+</para>
+<para>
+**Step 4**: Save all files and start the Codevis application using your terminal. You should see the messages in the
+console.
+</para>
+<para>
+Codevis comes with a builtin plugin editor that can be used for editing the plugins. To access it just click on
+`View > Plugin Editor`.
+</para>
+</refsect1>
+
 <refsect1>
 <title>See Also</title>