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.fisc...@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>