Document the plugins system

[benoit-pierre]

Document each type of plugin:

• the use-cases
• the API
• link to some examples

Document workflow:

• how to start a new plugin
• how to test a development version
• how to publish a version

[DanLanglois]

I see this:

https://pypi.org/project/plover-stenograph-usb/0.0.3/

One thing is it's not using zip but instead this is using tar. And that is a .tar file that has been wrapped in a .gz compression, and therefore, "random" access is not good on a .tar.gz. I mean, tar-gz is a "compressed archive". But zip / 7z are "archives of compressed files". I think, actually, that both file formats use the same compression algorithm (by default). Yet the .tar.gz format is created by first making an archive that puts all the (uncompressed) files into one .tar file. Then, that big archive file is compressed with the gzip method to create the final .tar.gz file. The point is that to get any one of the files from the archive you have to decompress the entire thing. This is very appropriate for backups or large transfers. Tar-balls are for backups. They are optimized for that purpose (e.g., dump a large folder full of files into a tar-ball, and recover it later, with everything preserved and with best full-archive compression). So I quibble, that it could be a lot easier (more appropriate) to use an off-the-shelf all-in-one format like zip that will allow you to extract individual files at a time.

[DanLanglois]

Perhaps there could be an online automated way of creating the basic files (skeleton). At least I wouldn't be stumped at the simple step of creating a webpage to be a form for this.

Create plugin skeleton files

Class name
Short title		Description for the plugin list

And so forth -- plugin version, minimum plover version, author/company name, email address. Perhaps something that resembles 'text of the menu item'. I don't know that 'menu item' is exactly what I mean, though it might be. I'm thinking back to my using such as SublimeText, and Eclipse, or, that is, using their plugins. That's too much architecture, surely, so I imagine that you can't be too flexible, here, this has to be simple. Therefore, I picture how a standard 'plugin' might require that you will install it and then see a 'Sample Menu' entry or such, somewhere -- 'in the menu', as it were.

I picture that submitting this form could return a zip file for download. That is to say, zip file with the class name as entered, etc. Inside, a folder with the class name. And inside that, python file with the class name. Maybe we find, as well, a form implementation, called Ui_ClassName.py, and also Ui_ClassName.ui. And so forth. Also, your 'plugin manager', would first need to retrieve some basic information about the plugin such as its name, description etc. I suppose that could be accomplished with a 'metadata.txt'. It could contain general info, version, name and some other metadata used. And 'used', here, would be not only 'used' by plugin infrastructure, but also by plugins website. Like this, perhaps:

PYTHON_PLUGINS_PATH/ MyPlugin/ metadata.txt --> required

Now, I look at plover_stenograph_usb-0.0.3.tar.gz, and it's got a folder inside: 'dist'. And inside that: 'plover_stenograph_usb-0.0.3.tar'. And inside that: 'plover_stenograph_usb-0.0.3'. And in there, well, first, I had been suggesting the idea of a 'metadata.txt', but also, I was wondering about maybe a init.py file. Not that I actually necessarily like that approach .. there is much to ponder here, kind of slick etc. I am sort of thinking out loud, and it's troublesome to actually read such a post, I imagine. I don't insist that this is useful for others. It may seem also, that everybody's a critic. It might be a shock to find what somebody manages to make of all this..

[morinted]

You're looking at the releases -- we release with setuptools and build sdist (source) and bdist_wheel (a python executable)

https://github.com/morinted/plover_stenograph_usb here is the repo which is what you'd actually worth with when making the plugin.

setup.cfg has a lot of the fields you mentioned.

On Sat, Jun 2, 2018, 4:43 AM DanLanglois notifications@github.com wrote:

Perhaps there could be an online automated way of creating the basic files (skeleton). At least I wouldn't be stumped at the simple step of creating a webpage to be a form for this. Create plugin skeleton files Class name Short title Description for the plugin list

And so forth -- plugin version, minimum plover version, author/company name, email address. Perhaps something that resembles 'text of the menu item'. I don't know that 'menu item' is exactly what I mean, though it might be. I'm thinking back to my using such as SublimeText, and Eclipse, or, that is, using their plugins. That's too much architecture, surely, so I imagine that you can't be too flexible, here, this has to be simple. Therefore, I picture how a standard 'plugin' might require that you will install it and then see a 'Sample Menu' entry or such, somewhere -- 'in the menu', as it were.

I picture that submitting this form could return a zip file for download. That is to say, zip file with the class name as entered, etc. Inside, a folder with the class name. And inside that, python file with the class name. Maybe we find, as well, a form implementation, called Ui_ClassName.py, and also Ui_ClassName.ui. And so forth. Also, your 'plugin manager', would first need to retrieve some basic information about the plugin such as its name, description etc. I suppose that could be accomplished with a 'metadata.txt'. It could contain general info, version, name and some other metadata used. And 'used', here, would be not only 'used' by plugin infrastructure, but also by plugins website. Like this, perhaps:

PYTHON_PLUGINS_PATH/ MyPlugin/ metadata.txt --> required

Now, I look at plover_stenograph_usb-0.0.3.tar.gz, and it's got a folder inside: 'dist'. And inside that: 'plover_stenograph_usb-0.0.3.tar'. And inside that: 'plover_stenograph_usb-0.0.3'. And in there, well, first, I had been suggesting the idea of a 'metadata.txt', but also, I was wondering about maybe a init.py file. Not that I actually necessarily like that approach .. there is much to ponder here, kind of slick etc. I am sort of thinking out loud, and it's troublesome to actually read such a post, I imagine. I don't insist that this is useful for others. It may seem also, that everybody's a critic. It might be a shock to find what somebody manages to make of all this..

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/openstenoproject/plover/issues/912#issuecomment-394070658, or mute the thread https://github.com/notifications/unsubscribe-auth/AFkgSjxm40D3atgrZaSkhm17NvDuDYoCks5t4lA2gaJpZM4SaktN .

[DanLanglois]

'setup.cfg has a lot of the fields you mentioned.'

The idea here being that setuptools provides special support for plugins. Like this:

setup.cfg .. name = plover_stenograph_usb version = 0.0.4 description = Stenograph USB protocol for Diamanté and Luminex machines for Plover ..

Sure, and, to resume this thread, I had in mind the idea of maybe providing an html form on a webpage, because this would be something that would be able to create all the necessary files and the boilerplate code for a plugin. I had the thought that 'submitting this form could return a zip file for download'. This would address 'how to start a new plugin'.

And, actually, looking at this again, it occurs to me that gee, maybe a plugin could do this!

It could provide a dialog with a form, so that we can fill the form with details relating to our plugin. I was thinking in terms of having a 'Plugin Builder', or, that is, something to 'Create a template for a Plover plugin'. There can be a template folder, or folders. The template folder can have a '.readme.tmpl', a 'module_name.tmpl'. And 'module_name.tmpl' can look like this:

class ${TemplateClass}Plugin: def init(self):

That's just a first pass. I wouldn't dive into writing a bunch of such material from scratch, but instead I could research some existing python projects. Creating a plugin architecture? It sounds hard. An advanced computer science concept, if you will. But okay, call it 'a dead simple plugin system'. We can spitball a template for 'init.py':

"""My version of the PluginBuilder plugin."""

all = ['PluginBuilder_plugin']

def PluginBuilder_plugin(): pass

def get_PluginBuilder_plugin(): return {'PluginBuilder': PluginBuilder_plugin}

And then, yes, also something goes into a setup.py.

Now this would handshake with a 'Plover.plugin_container module', or such. I go looking for a 'plugin_container.py', and I find this: 'plover-plugins-manager'. I'm a bit taken aback, that this is itself implemented as a plugin. I mean, actually, one installs the pluginmanager, as the first plugin? Confusing, because to get that far, Plover has to already have been setup for plugin management, and has to already have certain attributes and functions available. So there is, first, a basic Plugin Admin that is part of plover, "Setup version". And then, a plugin is loaded, called 'plover-plugins-manager'.

This does remind me of seeing how Plugin Manager is a plugin for Notepad++.

But I am just thinking out loud. Perhaps a bit cute of me to drop by every six months, and muse and puzzle a bit helplessly. I hope it's of any small use in documenting where the plugin framework is currently, and moving foreword.

I have a question about internal and external plugins, can you define internal plugins in the application code.. I try to guesss if plover-plugins-manager is able to update itself? I'm supposing that this could be thought of as just a Tab Module, only responsible for the look and feel and displaying each of the plugins registered against it..

[DanLanglois]

An addendum, about plugin module types. Various, plugin module types. I'm grasping at whether there is a pattern that many of the plugin module types follow. Such as, to provide an interface or abstract class which 'the plugin developer' implements or extends.

I picture a procedure like this:

1. To create a plugin, navigate to the Plover plugins directory.
2. Create a python file within your new folder and give it the same name.
3. Copy and paste [the code] into your plugin's python file and edit the information such as Plugin Name and Author.
4. Now that you've created a plugin, you can activate it.

Part of documenting such a procedure would be to say that 'the plugins will need to meet the specifications defined by our framework in order to run'. To implement a toy example, what do I need? For example, I could imagine something like this: 'Each plugin inherits from the base Python object and has a process() method. ' Nothing complex. Then, maybe Plover's run() method loops over all the plugins and calls each instance's process() function. Call that a 'simple' plugin methodology, for whatever that is worth. The 'simple' part, is what I'm wondering about -- such as, a standard API call for generating output. Maybe a required print_help method. If there are plugin types, then what is going to be consistent throughout, for them? Is there two separate subdirectories for two plugin types? I think it's a single plugin dictionary, but maybe with primary key/secondary key. And okay, all plugins of the same type will have exactly the same parameters for all standardized API calls? I may succeed in finding answers to all these questions, I hope this doesn't look like make-work for somebody else, but instead, a beginning towards listing some items for documentation:

--directory structure --the approach --plugin structure --plugin methodology core -- first pass: 'primary function to the plugin methodology is called 'loadPlugins' and is contained in 'mainScript''

[DanLanglois]

A thought -- could a 'Plover-Plugins' upload work, for pypi.org?

Thus, one setup.cfg and one setup.py. And then, a root 'readme', but also, child readme's, in subfolders. The root 'readme' could just be '# Plugins for Plover -- This library contains a set of plugins for Plover'.

To clarify why I suggest something here -- there are 35 Plover uploads to pypi.org:

plover 3.1.1 --Open Source Stenography Software plover-phenrsteno 0.2.3 --Phonemic non-rhotic English stenotype system for Plover plover-yaml-dictionary 0.0.1 --YAML dictionary support for Plover. plover-hjson-dictionary 0.0.2 --Hjson dictionary support for Plover plover_system_switcher 0.0.2 --Plover command plugin for switching systems. plover-last-translation 0.0.2 --Macro plugins for Plover to repeat output. plover-open-url 0.0.2 --Command plugin for Plover to open a URL plover-cat 0.1.3 --A CAT software for Plover plover-portuguese 0.2.1 --Portuguese language system for Plover plover-palantype 0.7.0 --Possum Palantype support for Plover plover-splits 0.0.1 --System for Plover that divides the left hand S plover-treal 1.0.1 --Tréal support for Plover plover-stitching 0.1.0 --Stitch words like T-H-I-S using Plover strokes plover-emoji 0.0.3 --Convert text to emoji with a stroke. plover-michela 0.1.6 --Michela (Italian system) support for Plover plover-midi 0.2.6 --MIDI keyboards/machines support for Plover plover-jaws 1.0a6 --Provides spoken feedback via the JAWS screen reader plover-excel-dictionary 0.2.4 --Excel dictionaries support for Plover plover-russian-trillo 0.0.1 --Russian realtime system for Plover plover-stenograph-usb 0.0.4 --Stenograph USB protocol for Diamanté and Luminex machines for Plover spectra-lexer 0.6.0 --Stroke and rule analyzer for stenography plover-layout-display 0.1.0 --Display the last stroke in Plover plover-windows-brightness 0.0.2 --Change Windows monitor brightness with Plover plover-python-dictionary 0.5.10 --Python dictionaries support for Plover plover-eclipse-dictionary 0.1.1 --Eclipse dictionary file support for Plover plover-digitalcat-dictionary 0.1.2 --DigitalCAT dictionary file support for Plover plover-plugins-manager 0.5.13 --Plugins manager for Plover plover-casecat-dictionary 0.1.3 --CaseCat dictionary file support for Plover plover-dict-commands 0.2.5 --Dictionaries stack manipulation commands for Plover plover-italian-stentura 0.5.6 --Italian Stentura support for Plover plover-retro-quotes 0.0.2 --Add single- and double-quotes to previously-typed words. plover_wpm_meter 0.2.2 --A meter to show your typing speed in Plover plover-dictionary-builder 0.0.4 --Build up a steno dictionary from text content plover-retro-case 0.1.2 --Retroactively change the case of an already written word plover-vlc-commands 0.6.5 --VLC commands for Plover

[nsmarkop]

a3947 from Discord and I have been working on documenting the current plugin system here: https://github.com/openstenoproject/plover/wiki/Plugins

We've documented most of the types with some examples of how they work so far. Still need to create templates of each type and document some things like the engine hooks probably.