QGIS Development with Plugin Builder and pb_tool
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 create
to create a config file. See the pb_tool website for more information.
Deploying
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
Getting Started
For details on installing and using pb_tool
, see:
http://g-sherman.github.io/pluginbuildtool