What is ths proper use of the 3 ‘requires’ options for the Gramps Plugin Registration system?
As an example, @kku has an experimental addon Tool plugin codenamed “FullText”. It leverages the Whoosh library.
@DavidMStraub was experimenting with Whoosh as a backend in GrampsWeb and has since switched to Sifts
How would the .gpr.py allow an addon to be distributed without creating multiple instances of Whoosh?
As far as I can see, the plugin system uses pip to install dependencies, so there is no duplication of packages if two addons depend on the same Python package. The only problem would be if two addons depend on two incompatible versions of the same package. Then only one would work.
The initial experiment simple has Whoosh copied as a subdirectory of the parent addon.
While I have no doubt that Kari will resolve that if the plugin ever moves beyond the ‘experimental’ stage, this is an opportunity to fill in a complete omission in the wiki’s discussion of the plugin registration.
The requires_mod entry specifies python modules that the addon requires. If you want to allow Gramps to try to install a module using pip, then it should be pure python. The Whoosh library is pure python.
The requires_gi entry specifies GObject introspection modules that are required. Gramps cannot install these.
The requires_exe entry specifies executables that must be present in the PATH. Again, the user must install these themselves.
Thank you! That filled in the empty descriptions in the wiki’s Gramplets: Register Options
found some registrations that could be linked in for syntax examples
Are these registration options specific to Gramplets, or could they be promoted to the Addons development wiki, and referenced in the Gramplets page?
Good question. We probably need to read the current core’s plugin registration module to determine which (kwargs ?) attributes are compatible with which plugin types. The Sphinx Plugin Register and utils documentation is out-of-date.
The help_url was promoted from being exclusively for GRAMPLET plugin type to being a generic option for all plugin registrations in Gramps 5.2 version. Adoption is uneven. And, as you are aware, approving Pull Requests to add a help_url to built-ins and Addons are low priority.
However, access to Help buttons in the GUI has also been inconsistent. A Help button for Gramplets only appears when a Gramplet is undocked. That makes Gramplet help an Easter Egg — since most users never undock gramplets. Many aren’t even aware that undocking is an option.
The Plugin Manager Enhanced gives access with a Help button for any plugin with that has a help_url in the registered plugin’s .gpr.py file. (And the Plugin Manager enhanced will exclude built-ins to list only Addons but not the reverse.) Hopefully, @prculley will be willing to add an debug mode Edit for the .gpr.py to complement the one for the plugin main module. It would make hacking in a help_url or fixing other Plugin Registration problems MUCH quicker.
The Addon Manager appears to need the help_url to be in the /listings/addons-en.json from one of its “Projects” to display a Wiki lozenge. Hacking in a help_url after installing is not noticed. It doesn’t deal with built-in plug-ins so users will be confused there too.
There has been some discussion of adding Help buttons to the toolbar’s Report and Tools selection dialog. With a future possibility of adding thumbnail previews to help recognizing a Report.
@kku has an experimental Reload Plugins addon tool