Development/Season of Docs/2019/MusicBrainz Picard

Ideas

Picard Developer Documentation Improvements

There already exists some basic documentation regarding the development of plugin modules for MusicBrainz Picard; however, it is somewhat sparse in content. The objective of this exercise is to provide a more complete guide including requirements, limitations, and specific examples to help ensure that plugins produced are of high quality and can be used on any platform supported by Picard. Some specific points include:

• Clarify the elements and information required for a plugin (e.g.: plugin information constants, standard license types, guidelines regarding description length). Provide a list and examples.
• Identify when the various types of plugins are executed and in what order.
• Identify and describe the information provided in the arguments to the various plugin types (e.g.: structure of the JSON / Dictionary for AlbumMetadata, TrackMetadata). Provide examples.
• Identify what information can be modified and saved, including both tag and non-tag information, and how the information can be saved.
• Identify and describe any limitations (e.g.: what Python modules are built into the Picard release and available for use).
• Include information regarding how to include and hook user interface elements (e.g.: settings page) for the plugin into the Picard user interface (e.g.: option settings tree), and how the user interface can be developed (e.g.: using Qt) and compiled (e.g.: using the Picard setup.py script's build-ui command).
• Include suggested best practices and development suggestions provided by the Picard developers.

Picard Scripting User Guide Improvements

There is already some documentation available regarding tags, tag mapping and scripting with MusicBrainz Picard; however, there is information missing regarding the scripting functionality in general and specific examples. The objective of this exercise is to provide a comprehensive, example-rich guide explaining Picard's built-in scripting language and utility. Specific information includes:

• An explanation of the different script types (i.e.: general scripts and file-naming scripts), where each is found in Picard's option settings, and at what points in the process they are executed.
• A complete list of all tags provided, along with descriptions and examples. This should also provide some explanation of how tags or non-tag variables can be added by plugins.
• An explanation of how to create new tags and non-tag variables within the scripts, along with examples.
• Examples of working script segments, including in-script code documentation, demonstrating how to perform specific functions.
• Examples of how the script segments can be combined to create custom file organization and naming scripts. Include examples of basic and complex naming scripts.