Plugin documentation

[killo3967]

I have been preparing for some time a documentation on how to create a plugin with all that it implies. For the moment I've left it in a repository of mine until the documentation is more mature so as not to mess up @maforget's wiki.
The link is https://github.com/killo3967/ComicRackCE-documentation/wiki
Please take a look at it and leave comments, if something is missing, not in place, missing or wrong.
I have not finished disassembling the DLL's until you give your approval of the format.
I look forward to your comments.
I also didn't want to upload this comment to Reddit until it passes through your wise hands first.

[maforget]

Not sure why you are dissembling DLL's? Which IronPython, ComicRack? no need for disassembly all the code is open source.

1. You talk about script headers: Why does it have python in it? It isn't a bash script that needs the shebangs.
2. In the section about header you talk about #@Debug or #@ConfigScript, these aren't a thing at all. ConfigScript is a hook and Debug doesn't exists.
3. You are missing the #@Enabled that tells if the plugin is initially enabled or not.
4. You are missing the #@Key that is required.
5. You are missing #@PCount for some smart list script.
6. You are missing #@Image to specify the image to use.
7. The required Framework is 4.8, but it isn't just required by ComicRack it's a main part on Windows, so it should already be present on all system. Might change if we go to the newer .NET as these aren't preinstalled.
8. Visual Studio 2017 is required if you want correct syntax in the program, but I've just use 2022 instead of keeping 2017 around. I just get use to the error because of print. The 2022 version will correctly debug the script, because it is the library doing the work, so it doesn't matter that it is supported or not.
9. I would say that to even install IronPython is not required, if fact the idea to copy the library to the Lib folder of ComicRack is a bad idea IMHO. It makes creating the plugin easier because you can just import library from the python install, but when a user wants install it, they will also have to install it their program dir (or another dir they configured in the settings). I guarantee you that a user will only install the plugin and will get an error, not knowing they also have to copy files in another dir or forget that it is required to do. That is not user friendly and is bound to create more headache, a user should install a crplugin and that's it.
   
   You didn't even mention that it is a required part of the process, so anyone following your guide will make a plugin just to have users say that it doesn't work. I mentioned it to you several time that fact in here and or Reddit about that fact (of the reason to go the full .NET plugin route). Check every plugin that is not a simple python script. Bedetheque & ComicVine Scraper, Library Organizer, Data Manager. etc all package the python files with it to avoid that. It is a very annoying process, I start my plugin, get an error about a missing file, copy that file, then another will be required and so on until you've copied maybe a dozen file. Also check my mini-manga scraper for a way to package library like json.
10. When talking about enabling Debug mode in the .ini file, the PythonDebug isn't the same as adding the -ssc -dso. That is required for the Visual Studio debugger to work, so it isn't an option, if you want to use the Visual Studio debugger you will need to have that enabled. As for the PythonEnableFrames, PythonEnableFullFrames not sure what these options do. Do you know what python frames are? I haven't really needed these option and not sure what they change.
11. Speaking of -dso, something I've witness and might need testing is that it only seems to work on the main .py file, if you are loading another python file from the first, I believe that required a restart.
12. KeepFiles isn't for file distributed with the plugin, but for files not distributed like setting file, that would be deleted on updating the plugin. It tells the program to keep them when you update it. It also now supports wildcard (check Data Manager).
13. The whole Part 4 is wrong at a lot of place. First it is still is Spanish. The function that you can run are not specific to an Hook like you mentioned. There are always available by using the word ComicRack, so for example the list used in ComicRack.App are those IApplication. Check my own documentation where I describe the command that can be called based on the interface. Same thing for Properties, like ProductVersion that is called with ComicRack.App.ProductVersion.
14. You don't mention the method parameters required for each hook, that is what is important. Ex: Knowing that using the Books hook, requires to pass 1 parameter that will be an array of ComicBook. Or that creating CreateBookList, you can set the number of parameters with the #@PCount. This seems important. Note that even the sample script for the Info Panel as errors in that regards.
15. Things like GetField or SetField aren't even a thing, they are GetCustomValue or SetCustomValue.
16. GetPageImage isn't also a thing in the ComicBook. It is ComicRack.App.GetComicPage(ComicBook cb, int page).
17. Part 6 is also not required at all. You mention a list of classes from ComicRack like DatabaseManager, that aren't directly exposed to the script. At this point you are just relisting existing code in ComicRack that users shouldn't really play without understanding the code. At this point pointing to the code should be the best instead of just listing existing code, that will probably change.
18. If you do want to access methods not exposed, You need to use reflection to do it. I've already found out how in this comment.
19. Don't forget this is IronPython, you can also use .NET libraries inside it.

I can respect you wanting to create documentation, but just ChatGPT-ing it without actual understanding will not help users. Also doesn't help if I have to review everything anyway. You should test some things out, figure out what is important. Just listing things that are either non existent or not adding important things isn't helpful.

You should also accept that user might need to check the code at some point, so instead of listing all the possible permutation (that normal script user shouldn't really be touching). Part of creating a script is a lot of figuring things out, you can point user to a direction. Show them example or tricks you've figure out, but we will never have a step by step recipe to create a script so that the average user can just create without thinking.

[killo3967]

1.- Don't understand what do you mean
2 to 7 .- Already corrected
8.- I think it's better 2017 than 2022 beacuse 2022 crashed too much and do not have ironpython intellysense.
9 - This is a point that I don't think we agree on. I think the IronPython standat library should be part of ComicRack. In fact inside the pathlib when you run a plugin it is defined. So why not use it to standardize the use of libraries when developing a plugin. If you want to use another library even if it has the same name, it is possible since the order of the sys.path are:

PATH: .
PATH: C:\Program Files "ComicRack Community Edition" Lib
PATH: C:\Program Files Community Edition Edition
PATH: C:\Users<user>\AppData\Roaming\cYoYoComicRack Community Edition\Scripts\Translate Summary Field with Google
As you can see it looks first in the local directory where the script is running and then in Lib, so even if you put all the ironpython 2.7.4 STDLIB hanging from \lib the ones you include in your plugin directory will run first.
Including the STDLIB libraries would allow for more compact and more standard plugins. Just as it is your choice whether or not to include these libraries as part of the ComicRackCE package, it is my choice to advise a future developer the advantage (in my opinion) of copying the libraries to make plugin development more convenient.
*** Translated with www.DeepL.com/Translator (free version) ***

[maforget]

I don't think you understand the point #9. It isn't about developing being more efficient. It is about the end user installing the plugin. They should not under any reason have to download IronPython and copy some files just to install a plugin. If you want the Lib folder to be part of the process for use then the user should not also have to do extra work. Trust me they will not. It's the developer problem, you are now giving the user more work to do to facilitate your work.

Why isn't the library part of ComicRack? I don't know if it might be part of the license or they must have had a good reason. But the fact is that it's been that way. I don't want to mess up with what has already been the way it's done for a long time.

You must think about existing users, that might not even want to use ComicRackCE and are using the original or an older version. The plugin should work for them also.

[maforget]

#1 is you declare the header starting with the word python like it's a bash script and you need to decorate it so it knows the type of script it is. This isn't required at all.

[maforget]

For point 8, I do not like the idea of having to use old software that is already hard to get (there are no more links to the installer on their front page). Maybe developing an environment like ComicVine Scraper has use to work in Visual Code could be better.

[killo3967]

10.- The frame configuration options are part of the IronPython stack. It's like running "ipy -X:Frames or -X:FullFrames" and this allows you to inspect the frame stack, for example when importing external libraries or other modules. This makes the processing a bit slower but more flexible.

[maforget]

I am not a Python dev, so I would need to look into it, but from my experience it had no incidence in the debugging values Visual Studio showed. What exactly does it add, aka what are frames?

[killo3967]

11.- You are right, I have seen the same behaviour. I think there is no need for any switch on ComicRack startup, just change the configuration ofcomicrack.ini. What do you think ?

[maforget]

They are still very useful for developing. You could set them all in the .ini, but that would probably require having a separate dev environment. Either using the -ac switch to create an AlternateConfig or using a portable folder. That should be part of your guide. It is still useful when testing the plugin on a full library to have at least a script output to see errors.

[killo3967]

12.- Corrected

[killo3967]

Regarding point 13, it's a topic I'd like to clarify because I thought I had it under control, but I see that's not the case.
So there are some hooks associated with the interfaces and these have a common link called IPluginEnvironment.
Now I'm confused, what's the point of defining a hook in the plugin? Can I define the books hook and then call the comicrack.comicdisplay.zoom method?

[maforget]

The hooks and what is in IPluginEnvironment are 2 things. The properties in IPluginEnvironment refer to an object that is set by the plugin engine. They are accessed by the keyword ComicRack, that is a variable set by the engine that will work regardless of Hooks. It references some classes in the CR code that can be called by the plugin. So in your example yes you could call ComicRack.ComicDisplay.ZoomTo from a Books hook, it might not work because the ComicDisplay might not be opened in that case, so you would need to check for validity, it would probably me more useful with BookOpened or ReaderResized, but nothing is stopping you from calling it anywhere.

Hooks are what type of plugin they are. Books is the most use, if you want a plugin to appear in the info dialog, you use Editor. If you want one under the File dialog it is Library. If you want a custom smart list then it is CreateBookList. The type of hooks will determine the signature of the method you define. You want to create a search plugin that will search a specific site, you create a NetSearch plugin. But in that case the signature will not be def function(books) but def function(hint, text, limit).

They are defined here

ComicRackCE/ComicRack.Plugins/PythonCommand.cs

Lines 145 to 214 in 763bfaa

	hookTypes = new Dictionary<string, ScriptCreateHandler>
	{
	{
	PluginEngine.ScriptTypeLibrary,
	(ScriptScope s, string n) => s.GetVariable<Action<ComicBook[]>>(n)
	},
	{
	PluginEngine.ScriptTypeBooks,
	(ScriptScope s, string n) => s.GetVariable<Action<ComicBook[]>>(n)
	},
	{
	PluginEngine.ScriptTypeNewBooks,
	(ScriptScope s, string n) => s.GetVariable<Action<ComicBook[]>>(n)
	},
	{
	PluginEngine.ScriptTypeParseComicPath,
	(ScriptScope s, string n) => s.GetVariable<Action<string, ComicNameInfo>>(n)
	},
	{
	PluginEngine.ScriptTypeBookOpened,
	(ScriptScope s, string n) => s.GetVariable<Action<ComicBook>>(n)
	},
	{
	PluginEngine.ScriptTypeCreateBookList,
	(ScriptScope s, string n) => s.GetVariable<Func<ComicBook[], string, string, IEnumerable<ComicBook>>>(n)
	},
	{
	PluginEngine.ScriptTypeReaderResized,
	(ScriptScope s, string n) => s.GetVariable<Action<int, int>>(n)
	},
	{
	PluginEngine.ScriptTypeSearch,
	(ScriptScope s, string n) => s.GetVariable<Func<string, string, int, Dictionary<string, string>>>(n)
	},
	{
	PluginEngine.ScriptTypeConfig,
	(ScriptScope s, string n) => s.GetVariable<Action>(n)
	},
	{
	PluginEngine.ScriptTypeStartup,
	(ScriptScope s, string n) => s.GetVariable<Action>(n)
	},
	{
	PluginEngine.ScriptTypeShutdown,
	(ScriptScope s, string n) => s.GetVariable<Func<bool, bool>>(n)
	},
	{
	PluginEngine.ScriptTypeComicInfoHtml,
	(ScriptScope s, string n) => s.GetVariable<Func<ComicBook[], string>>(n)
	},
	{
	PluginEngine.ScriptTypeComicInfoUI,
	(ScriptScope s, string n) => s.GetVariable<Func<Control>>(n)
	},
	{
	PluginEngine.ScriptTypeQuickOpenHtml,
	(ScriptScope s, string n) => s.GetVariable<Func<ComicBook[], string>>(n)
	},
	{
	PluginEngine.ScriptTypeQuickOpenUI,
	(ScriptScope s, string n) => s.GetVariable<Func<Control>>(n)
	},
	{
	PluginEngine.ScriptTypeDrawThumbnailOverlay,
	(ScriptScope s, string n) => s.GetVariable<Action<ComicBook, Graphics, Rectangle, int>>(n)
	}
	};
	settings = IniFile.Default.Register<PythonSettings>();
	Optimized = true;
	}

Example:

NetSearch

#@Name GetComics Search
#@Hook NetSearch
#@Enabled false
#@Image GetComics.png
#@Description Adding GetComics Search
def GetComicsSearch(hint, text, limit):

ConfigScript

#@Key   BookHasBeenOpened
#@Hook  ConfigScript
def ConfigureBookHasBeenOpened ():
	MessageBox.Show ("Should open a window to configure the script!")

CreateBookList

#@Hook	 CreateBookList
#@PCount 1
#@Enabled false
#@Description Sample script to show how to write custom smartlist scripts
def GetBooksWith (books, a, b):

See how they all have different signatures.

[killo3967]

So does this seem like a more adequate explanation of what a ComicRackCE hook is?

Hooks in ComicRackCE are integration mechanisms that allow scripts and plugins to automatically execute code at specific points in the ComicRackCE lifecycle.

Each hook defines when the script will be called (e.g. when starting ComicRack, opening a comic, resizing the reader) and what kind of ComicRack context will be available.

Hooks do not create or prepare a new environment: they insert your code into the pre-existing environment of the program at that moment.

To use a hook, a script must explicitly declare the type of hook it implements (e.g. Startup, BookOpened, Shutdown, ComicInfoHtml, etc.), and ComicRackCE will automatically call it when appropriate.

[maforget]

I mean not necessarily automatically. Things like Books need to be called manually. It also affects what the function signature will be and what type of objects will be passed and what needs to return.

Also don't forget to add Samples that are usually what is missing in a lot of docs.

Also a tip on discussion on GitHub, there are threads where we continue the discussion on a specific topic. Try to continue where I answered instead of starting a new thread. It is hard to follow. Check on the site not via email.