The Plugin Builder is a great tool for generating a working plugin project that you can customize.
One of the main tasks in the development cycle is deploying the plugin to the QGIS plugin directory for testing. Plugin Builder comes with a Makefile that can be used on Linux and OS X to aid in development. Depending on your configuration, the Makefile may work on Windows.
To help in managing development of your projects, we've come up with another option---a Python tool called pb_tool, which works anywhere QGIS runs.
Here's what it provides:
Usage: pb_tool [OPTIONS] COMMAND [ARGS]... Simple Python tool to compile and deploy a QGIS plugin. For help on a command use --help after the command: pb_tool deploy --help. pb_tool requires a configuration file (default: pb_tool.cfg) that declares the files and resources used in your plugin. Plugin Builder 2.6.0 creates a config file when you generate a new plugin template. See http://g-sherman.github.io/plugin_build_tool for for an example config file. You can also use the create command to generate a best-guess config file for an existing project, then tweak as needed. Options: --help Show this message and exit. Commands: clean Remove compiled resource and ui files clean_docs Remove the built HTML help files from the... compile Compile the resource and ui files create Create a config file based on source files in... dclean Remove the deployed plugin from the... deploy Deploy the plugin to QGIS plugin directory... doc Build HTML version of the help files using... list List the contents of the configuration file translate Build translations using lrelease. validate Check the pb_tool.cfg file for mandatory... version Return the version of pb_tool and exit zip Package the plugin into a zip file suitable...
In the command summary, a description ending in ... means there is more to see using the help switch:
pb_tool zip --help Usage: pb_tool zip [OPTIONS] Package the plugin into a zip file suitable for uploading to the QGIS plugin repository Options: --config TEXT Name of the config file to use if other than pb_tool.cfg --help Show this message and exit.
The Configuration File
pb_tool relies on a configuration file to do its work. Here's a sample pb_tool.cfg file:
# Configuration file for plugin builder tool # Sane defaults for your plugin generated by the Plugin Builder are # already set below. # [plugin] # Name of the plugin. This is the name of the directory that will # be created in .qgis2/python/plugins name: TestPlugin [files] # Python files that should be deployed with the plugin python_files: __init__.py test_plugin.py test_plugin_dialog.py # The main dialog file that is loaded (not compiled) main_dialog: test_plugin_dialog_base.ui # Other ui files for dialogs you create (these will be compiled) compiled_ui_files: foo.ui # Resource file(s) that will be compiled resource_files: resources.qrc # Other files required for the plugin extras: icon.png metadata.txt # Other directories to be deployed with the plugin. # These must be subdirectories under the plugin directory extra_dirs: # ISO code(s) for any locales (translations), separated by spaces. # Corresponding .ts files must exist in the i18n directory locales: af [help] # the built help directory that should be deployed with the plugin dir: help/build/html # the name of the directory to target in the deployed plugin target: help
The configuration file is pretty much self-explanatory and represents that generated by Plugin Builder 2.6 for a new plugin. As you develop your code, you simply add the file names to the appropriate sections.
Plugin Builder 2.6 will be available the week of the QGIS 2.6 release. In the meantime, you can use
pb_tool createto create a config file. See the pb_tool website for more information.
Here's what a deployment looks like with pb_tool:
$ pb_tool deploy Deploying will: * Remove your currently deployed version * Compile the ui and resource files * Build the help docs * Copy everything to your .qgis2/python/plugins directory Proceed? [y/N]: y Removing plugin from /Users/gsherman/.qgis2/python/plugins/TestPlugin Deploying to /Users/gsherman/.qgis2/python/plugins/TestPlugin Compiling to make sure install is clean Skipping foo.ui (unchanged) Compiled 0 UI files Skipping resources.qrc (unchanged) Compiled 0 resource files Building the help documentation sphinx-build -b html -d build/doctrees source build/html Running Sphinx v1.2b1 loading pickled environment... done building [html]: targets for 0 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found no targets are out of date. Build finished. The HTML pages are in build/html. Copying __init__.py Copying test_plugin.py Copying test_plugin_dialog.py Copying test_plugin_dialog_base.ui Copying foo.py Copying resources_rc.py Copying icon.png Copying metadata.txt Copying help/build/html to /Users/gsherman/.qgis2/python/plugins/TestPlugin/help
For details on installing and using