From af76442149d39e07f65edab1b19617bff586a4a4 Mon Sep 17 00:00:00 2001 From: Joel Collins Date: Mon, 7 Jan 2019 17:07:28 +0000 Subject: [PATCH] Added link to packaging --- docs/source/plugins.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 6a57425b..e8e9076d 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -15,15 +15,15 @@ Here, ```` is an instance of :py:class:`openflexure_microscop Plugins can either be loaded as a single Python file located anywhere on disk, or as a Python package installed to the environment being used. If loaded from a single file, the namespace is set to the file name (excluding .py extension) of the plugin file. If loaded from a package, the namespace is set to the name of the top-level module in the package. For example, if your plugin class definition resides within ``my_openflexure_plugins.microscope.mypluginpackage``, the namespace will be set to ``mypluginpackage``. Where possible, try to use descriptive, unique package names for this reason. For example, rather than name your plugin package ``autofocus``, which would like cause namespace clashes, instead name it ``yourname_autofocus``, or similar. -Single-file plugins -+++++++++++++++++++ +Module (single-file) plugins +++++++++++++++++++++++++++++ For adding simple functionality, such as a few basic functions and API routes, a single Python file can be loaded as a plugin. This Python file must contain all of your plugin classes. Relative imports will not work. External modules and packages can be used with absolute imports, however for more complex plugins, it is often worth instead making use of an installable package plugin. Package plugins +++++++++++++++ -Generally, for adding anything other than very simple functionality, plugins should be written as installable Python packages. This has the advantage of allowing relative imports, so functionality can be easily split over several files. For example, class definitions associated with API routes can be separated from class definitions associated with the microscope plugin. +Generally, for adding anything other than very simple functionality, plugins should be written as `package distributions `_. This has the advantage of allowing relative imports, so functionality can be easily split over several files. For example, class definitions associated with API routes can be separated from class definitions associated with the microscope plugin. The main restriction is that the plugin package must be importable using an absolute import from within the Python environment being used to load your microscope.