I have recently developed two plugins for Calibre. I have an extensive background in Web Development and programming. Took me about a week to develop the two plugins, but I feel it could have been faster.
Just want to give a little feedback on the Documentation and my experience.
The documentation is very lacking, and I found myself repeatedly downloading other people's work to get examples of how specific features of Calibre work.
I constantly had to stack trace back through thousands of lines of code from the source code, to work out what the input and expected outputs of the abstraction-layered functions do. The documentation isn't clear enough, and not enough examples are given.
There are places both in the user guide and the code comments where terminology is ambiguous. Calibre deals with ebook readers with SD cards, it also formats code, as well as working with file formats.
format_metadata()
Does that mean "Format" (Delete) the metadata on the SD Card?
Provide "File Format" (Type) Metadata?
or "Format" (Organise) the code related to the metadata?
format_abspath()
Does that mean "Format" (Delete) the data at the absolute path?
Provide the "File Format" (Type) path?
or "Format" (Organise) the path using the os path separator?
In English, the meaning of Format can mean multiple things depending on the context. (Delete, Organise, Storage Type) When dealing with people's files and databases, making the distinction between them is of utmost importance.
Flow direction.. There are no `get` or `set` instructions before each function to tell the user the flow direction of the data. For instance, if the function names were written as `get_file_format_metadata`, this would be clearer about the flow direction, clearly explaining the exact context of the command.
There are places in the documentation where it seems like you're trying to explain Quantum Physics to your dog lol. When dealing with searching the database in the documentation, it states:
Query: This is the Query variable you send the Query to be queried?
Thats's all you get as an explanation.
No details on the type of query expected by the function, SQL string, dict, tuple, list, kwargs.
No details on what type of data the function returns?
Some of the comments in the code make no sense at all:
`isn't supported in by the obsolete library.database2. Use db.legacy.LibraryDatabase instead`
Obsolete means old, but library.database2 is the location of the "new_api" function you tell users to use. So is the new function obsolete, and do we have to use the legacy version? Because Legacy means old as well.
Just things like that bamboozled me, as none of it makes sense.
Now, after explaining the above, it doesn't take away from the great work you have done with the software. I understand it has been nearly 20 years of coding, and I understand that updating documentation on an ongoing project is a tedious task. I feel your pain.. I'm not trying to be negative or put the project down, just trying to provide some positive criticism.
There are tools out there to rewrite Python functions en mass, to better explain their understanding, dataflow and context and readability for others.
There are also tools for creating detailed documentation, using standard tools such as doc-string comments in the code to automatically build and update the documentation in multiple formats as you code.. new tools such as A.I documentation writers, etc, that are very effective. Might be worth a look at doing, when you get some time
https://www.sphinx-doc.org/en/master/