| Thread Previous • Date Previous • Date Next • Thread Next |
Best Regards Simon Am 2017-06-27 21:49, schrieb Wayne Stambaugh:
This looks good. Anyone else find any issues with it? You do not needto change the Doxygen configuration files. Someone modified them to useall *.md files in the appropriate search paths. Please post the patch created by git format-patch and post it as an attachment and I will commit it if no one objects. On 6/18/2017 11:25 AM, Simon Küppers wrote:I made some adjustments to the documentations. https://github.com/skuep/kicad-source-mirror/blob/devel/Documentation/development/pcbnew-plugins.md I did not write something about adding paths to the python runtime environment since I don't use this feature (and don't want to ;-)) because I don't feel comfortable getting so close the the Python internals. Also you have to be somewhat careful to not break cross-platform support. The PEP 8 was not particularly helpful, I agree. I changed it. How do I add the document to the "Doxygen configuration file" (the Doxyfile?). From what I know of Doxygen, it pulls all files that match the given file extensions (which include *.md). PS: English capitalization and comma rules always give me a headache, sorry! ;-) Anyway, keep the comments incoming. Best Regards Simon Am 17.06.2017 um 15:41 schrieb Wayne Stambaugh:Simon, Please be patient. I know things have been a bit slow on the mailinglist recently. This is not that unusual in the summer as developers areon vacation or busy doing other things. I took a look at your document and have the following comments: Avoid referring to the Python plugin as a new feature. This willeliminate the need to go back and change the document when it no longer is a new feature. The Python plugin support has been around for a fewyears. Only the action plugin in support is new.The title should read "Python Plugin Development for Pcbnew" using titlecapitalization as shown. It's common to use title capitalization for all section titles. All the section titles in your document use sentence capitalization."Pcbnew" should always be capitalized since it is a proper noun and isthe official name. PEP 8 is the Python coding standard. This doesn't seem like it's related to Python packaging. Are you sure this is the correct PEP?It might not be a bad idea to let developers know that additional pathscan be added to the Python runtime environment when designing complexplugins using the sys.path or the equally handy PYTHONPATH environment variable. This handy Python feature is often overlooked by developersnew to Python. Your patch does not add the new document to the Doxygen configuration file so it will not get added to to the developers documentation.Would someone with more knowledge about the Pcbnew Python plugin supportverify that this information is correct? It looks fine to me but I'm not completely familiar with the new action plugin support. Cheers, Wayne On 6/17/2017 5:59 AM, Simon Küppers wrote:Since there hasn't been any followup, attached is the patch. Best Regards! _______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
From ab88d592d96089df2ee2e03dbf18780e33a0f06c Mon Sep 17 00:00:00 2001
From: Simon Kueppers <simon.kueppers@xxxxxx>
Date: Tue, 27 Jun 2017 23:10:36 +0200
Subject: [PATCH 1/1] Added documentation about pcbnew plugin development
---
Documentation/development/pcbnew-plugins.md | 111 ++++++++++++++++++++++++++++
1 file changed, 111 insertions(+)
create mode 100644 Documentation/development/pcbnew-plugins.md
diff --git a/Documentation/development/pcbnew-plugins.md b/Documentation/development/pcbnew-plugins.md
new file mode 100644
index 0000000..1066f52
--- /dev/null
+++ b/Documentation/development/pcbnew-plugins.md
@@ -0,0 +1,111 @@
+# Python Plugin Development for Pcbnew #
+
+## Introduction ##
+KiCad implements a Python plugin interface so that external Python plugins can be run from within Pcbnew.
+The interface is generated using the `Simplified Wrapper and Interface Generator` or [SWIG](http://www.swig.org).
+SWIG is instructed to translate specific C/C++ header files into other languages using `interface` files.
+These files ultimately decide what C/C++ functions, classes and other declarations are exported and can be found in `pcbnew/swig/`.
+
+During build-time the SWIG interface files are used to generate the corresponding .py files.
+These files are installed into Python's system-wide `dist-packages` repository, thus they can be imported by any Python 2 interpreter installed on the system.
+
+## Existing Pcbnew Python API documentation ##
+The Pcbnew Python API can be used stand-alone, i.e. no instance of Pcbnew is running and the board project to be manipulated is loaded and saved from and to file.
+This approach is shown with some examples in the [user's documentation](http://docs.kicad-pcb.org/stable/en/pcbnew.html#_kicad_scripting_reference).
+
+Another documentation source is the auto-generated doxygen reference of the API. It can be found [here](http://docs.kicad-pcb.org/doxygen-python/namespacepcbnew.html).
+
+## `Action Plugin` Support ##
+Besides the stand-alone usage of the generated Python plugin interface, additional support regarding online manipulation of board projects is available for Pcbnew.
+Plugins using this feature are called `Action Plugins` and they are accessible using a Pcbnew menu entry that can be found under `Tools->External Plugins`.
+KiCad plugins that follow the `Action Plugin` conventions can be made to show up as external plugins in that menu.
+The user can run the plugin resulting in calling a defined entry function in the Python plugin's code.
+This function can then be used to access and manipulate the currently loaded board from the Python script environment.
+
+### Typical Plugin Structure ###
+The `Action Plugin` support is implemented in Pcbnew by discovering Python packages and Python script files in specific directories on startup.
+In order for the discovery process to work, the following requirements must be met.
+
+* The plugin must be installed in the KiCad plugins search paths as documented in `scripting/kicadplugins.i`.
+ (Currently on a Linux Mint Installation this is /usr/share/kicad/scripting/plugins/ and ~/.kicad_plugins/)
+* Alternatively a symbolic link can be created in the KiCad plugin path link to the plugin file/folder in another location of the filesystem. This can be useful for development.
+* The plugin must be written as a simple Python script (*.py) located in the plugin search path.
+ Note that this method is preferred for small plugins consisting of a single .py file.
+* Alternatively the plugin must be implemented as a Python package conforming to the Python package standard definitions (See [6.4. Packages](https://docs.python.org/2/tutorial/modules.html#packages)).
+ Note that this method is preferred for larger plugin projects consisting of multiple .py files and resource files such as dialogs or images.
+* The Python plugin must contain a class derived from `pcbnew.ActionPlugin` and it's `register()` method must be called within the plugin.
+
+The following examples demonstrate the plugin requirements.
+
+### Simple Plugin Example ###
+The folder structure of the simple plugin is fairly straight forward.
+A single Python script file is placed into a directory that is present in the KiCad plugin path.
+
+ + ~/.kicad_plugins/ # A folder in the KiCad plugin path
+ - simple_plugin.py
+
+The file `simple_plugin.py` contains the following.
+
+ import pcbnew
+
+ class SimplePlugin(pcbnew.ActionPlugin):
+ def defaults(self):
+ self.name = "Plugin Name as shown in Pcbnew: Tools->External Plugins"
+ self.category = "A descriptive category name"
+ self.description = "A description of the plugin and what it does"
+
+ def Run(self):
+ # The entry function of the plugin that is executed on user action
+ print("Hello World")
+
+ SimplePlugin().register() # Instantiate and register to Pcbnew
+
+### Complex Plugin Example ###
+The complex plugin example represents a single Python package that is imported on Pcbnew startup.
+When the Python package is imported, the `__init__.py` file is executed and is thus a perfect place to instantiate and register the plugin to Pcbnew.
+The big advantage here is, that you can modularize your plugin much better and include other files without cluttering the KiCad plugin directory.
+Additionally, the same plugin can be executed standalone using `python -m` e.g. to perform tests on the Python code.
+The following folder structure shows how complex plugins are implemented:
+
+ + ~/.kicad_plugins/ # this directory has to be in the plugin path
+ + complex_plugin/ # The plugin directory (A Python package)
+ - __init__.py # This file is executed when the package is imported (on Pcbnew startup)
+ - __main__.py # This file is optional. See below
+ - complex_plugin_action.py # The ActionPlugin derived class lives here
+ - complex_plugin_utils.py # Other Python parts of the plugin
+ + otherstuff/
+ - otherfile.png
+ - misc.txt
+
+It is recommended to name the file containing the ActionPlugin derived class as `<package-name>_action.py`.
+In this case the file is named `complex_plugin_action.py` with the following contents:
+
+ import pcbnew
+
+ class ComplexPluginAction(pcbnew.ActionPlugin)
+ def defaults(self):
+ self.name = "A complex action plugin"
+ self.category = "A descriptive category name"
+ self.description "A description of the plugin"
+
+ def Run(self):
+ # The entry function of the plugin that is executed on user action
+ print("Hello World")
+
+The `__init__.py` file is then used to instantiate and register the plugin to Pcbnew as follows.
+
+ from .complex_plugin_action import ComplexPluginAction # Note the relative import!
+ ComplexPluginAction().register() # Instantiate and register to Pcbnew
+
+As described in [PEP 338](https://www.python.org/dev/peps/pep-0338/) Python can execute packages (or modules) as scripts.
+This can be useful to implement a command-line stand-alone version of your KiCad plugin with minimum effort.
+In order to implement this feature, a `__main__.py` file is created in the package directory.
+This file can be executed by running the following command.
+
+ python -m <package_name>
+
+Make sure that your current directory is the parent directory of the package directory when running the command.
+In these examples, this would be `~/.kicad_plugins`.
+When running the command the Python interpreter runs `/complex_plugin/__init__.py` followed by `/complex_plugin/__main__.py`.
+
+
--
2.7.4
| Thread Previous • Date Previous • Date Next • Thread Next |
