Insert toolkits

INSTALL

@@ -0,0 +1,114 @@
+========================================
+Building and installing a Gamera toolkit
+========================================
+
+This is generic information about building and installing a Gamera
+toolkit.
+
+**Please make sure that Gamera is built and fully installed before
+proceeding.**
+
+Gamera can be downloaded at http://gamera.informatik.hsnr.de/
+
+Linux (and other \*nix)
+=======================
+
+Install binary packages for Python and wxPython (see correct versions
+at top of this document.)
+
+In addition, your Linux installation should also have:
+
+- libtiff 3.5.x
+- libpng 2.2.x
+- libz
+
+Standard Build and Install
+--------------------------
+
+Gamera toolkits are built using the Python-standard Distutils system.  Open a
+terminal and type::
+
+  python setup.py build
+  sudo python setup.py install
+
+Mac OS-X
+========
+
+OS-X support can be considered working but preliminary at this point.
+Gamera toolkits will only run on El Capitan( 10.11).  We do not plan to support
+earlier versions.  You will need to install the GNU development tools
+(gcc, g++, ld etc.), X11, and Python 3.5 or newer.
+
+Prerequisites
+-------------
+
+wxPython comes in two flavors for OS-X: a native Carbon-based one that
+follows the look-and-feel of OS-X, and a version built on top of
+Gtk+/X11.  The native Carbon version is currently too incomplete to be
+usable for Gamera.  Since there is no official build of the
+Gtk+/X11 version, I have made one available in the Gamera
+SourceForge Files section.
+
+Standard Build and Install
+----------------------------
+
+Download and install the unoffical wxPython-Gtk-X11 distribution from
+the Gamera Files section on SourceForge.
+
+  Alternatively, you can install fink and then build the package
+  wxPython-Py40, which is currently in the unstable branch, (and its
+  dependencies) from source.  You will then need to use the fink
+  version of Python (not the one that Apple provides) to carry out the
+  instructions below.
+
+Gamera is built using the Python-standard Distutils system.  
+
+To build Gamera, open a X11 terminal and type::
+
+  python setup.py build
+
+and then to install (you'll need to have admin priviledges)::
+
+  sudo python setup.py install
+
+The scripts can be installed by::
+
+  sudo python setup.py install_scripts -d /usr/bin
+
+.. note:: The ``-d /usr/bin/`` installs the scripts in a reasonable
+  place on the PATH.  If you do not specify it, the scripts are by
+  default installed to ``/System/Library/Frameworks/Python.framework/Versions/3.5/bin``.
+
+Building the documentation
+==========================
+
+Once the the toolkit is built, the documentation can be
+generated and converted to HTML.
+
+Prerequisites
+-------------
+
+Generating documentation requires two third-party Python
+libraries:
+
+  - docutils_ (version 0.3 or later) for handling reStructuredText documents.
+
+  - SilverCity_ (version 0.9 or later) for colorizing source code.
+
+.. _docutils: http://docutils.sourceforge.net/
+.. _SilverCity: http://silvercity.sourceforge.net/
+
+Generating
+----------
+
+To generate the documentation, go to the ``doc`` directory and run the
+``gendoc.py`` script.
+
+Alternatively, you can call the ``gendoc.py`` script with the
+documentation directory as a commandline argument::
+
+   gendoc.py -d /path/to/doc
+
+The output will be placed in the ``doc/html/`` directory.  The contents of
+this directory can be placed on a webserver for convenient viewing.
+

LICENSE

@@ -0,0 +1,6 @@
+This skeleton of a Gamera toolkit is released under the public domain.
+Unlike the Gamera code itself, which is under the terms of the GNU
+General Public License, you may do anything you wish with the code
+under this directory.
+
+Michael Droettboom (2004)

MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-include src *.cpp *.c *.h makefile.* *.hpp *.hxx *.cxx *.txt ANNOUNCE CHANGES INSTALL KNOWNBUG LICENSE README TODO Y2KINFO
+recursive-include include *.cpp *.c *.h makefile.* *.hpp *.hxx *.cxx *.txt ANNOUNCE CHANGES INSTALL KNOWNBUG LICENSE README TODO Y2KINFO
+recursive-include scripts skeleton
+include INSTALL LICENSE README rename.py MANIFEST.in
+recursive-include doc *.txt *.css *.py *.jpg *.jpeg *.png *.gif

PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 1.0
+Name: skeleton
+Version: 2.2.0pre2
+Summary: UNKNOWN
+Home-page: UNKNOWN
+Author: UNKNOWN
+Author-email: UNKNOWN
+License: UNKNOWN
+Description: UNKNOWN
+Platform: UNKNOWN

README

@@ -0,0 +1,139 @@
+Writing Gamera toolkits
+=======================
+
+(c) 2004 Michael Droettboom
+
+What is a toolkit?
+------------------
+
+A toolkit is a way to distribute code that uses Gamera but is not
+included in the Gamera source tree.  This could be entire
+applications that process images and return symbolic
+results (eg. an OCR package), or simply a library of utility
+functions (eg. for color image processing).
+
+The Gamera toolkit framework actually provides very little beyond the
+standard Python package and module system on which it is based:
+
+- A special Python distutils-based framework for building Gamera
+  plugins more conveniently.
+- Support for adding a toolkit-specific drop-down menu to the Gamera
+  GUI.
+
+If neither of these features is necessary for your project, you may
+decide to simply release your application or library as a standard
+Python package.
+
+Creating a toolkit
+------------------
+
+The directory heirarchy
+```````````````````````
+
+Toolkits require a number of different files in a directory
+heirarchy.  Here we assume the toolkit is called ``my_toolkit``.
+
++----------+----------------------------------------------------------------+
+| ./       | Basic information files for building the toolkit               |
+|          +---------------+------------------------------------------------+
+|          | setup.py      | A Python ``distutils``-based build script.     |
++----------+---------------+------------------------------------------------+
+| gamera/  | All the files needed by Gamera at runtime.                     |
+|          | Since Python is interpreted, these means                       |
+|          | Python source files.                                           |
+|          +---------------+------------------------------------------------+
+|          | toolkits/     | This is where the Python source code of the    |
+|          | my_toolkit    | toolkit goes.                                  |
+|          +---------------+------------------------------------------------+
+|          | toolkits/     | This is where the Gamera plugins for the       |
+|          | my_toolkit/   | toolkit go.                                    |
+|          | plugins/      |                                                |
++----------+---------------+------------------------------------------------+
+| include/ | C++ header (``.hpp``) files.                                   |
+|          +---------------+------------------------------------------------+
+|          | plugins/      | Source code for the C++-based plugins.         |
++----------+---------------+------------------------------------------------+
+
+Some toolkits may go beyond this, of course, by including ``.cpp``
+files in a ``src/`` directory or documentation in a ``doc/``
+directory.
+
+.. note:: At present, toolkit documentation does not compile along
+   with the main Gamera documentation.  I have not yet decided whether
+   this should be considered a feature or a bug.
+
+The skeleton toolkit
+````````````````````
+
+For convenience, a minimal skeleton of a toolkit is provided and
+available from the files section of the `Gamera github site`__.
+
+.. __: https://github.com/hsnr-gamera
+
+This skeleton provides the very minimum needed to create a toolkit.
+You will need to change all the references to the toolkit name
+(Skeleton) throughout its source.  The ``rename.py`` script is
+provided for this purpose. For example::
+
+  python rename.py my_toolkit
+
+will rename and edit all of the files to create a new toolkit called
+``my_toolkit``.
+
+Editing the files
+`````````````````
+
+The files included in the skeleton toolkit are self-documenting.  They
+should require only minimal editing.  Mainly, toolkit authors will be
+adding their own Python modules and Gamera plugins to the toolkit.
+
+setup.py
+''''''''
+
+You only need to edit this file if you are doing anything more complex
+than installing Python modules and building Gamera plugins.  For
+instance, if you are building and linking to a third-party library.
+Since this script is based on Python distutils, the distutils
+documentation is the best resource for how to do that.
+
+MANIFEST.in
+'''''''''''
+
+If you need to include more data files to your toolkit distrubution,
+you will need to edit this file.  The format is described in the
+distutils documentation.
+
+gamera/toolkits/my_toolkit/__init__.py
+''''''''''''''''''''''''''''''''''''''
+
+If you want to add a drop-down menu to the Gamera GUI shell, you can
+edit this file.  It is self-documenting.  You will probably want to
+remove the example menu items that are included in the skeleton.
+
+Plugins
+'''''''
+
+Writing plugins is described in detail here__.  The Python metadata
+files for a toolkit go in ``gamera/toolkits/my_toolkit/plugins/``, and
+the C++ source code goes in ``include/plugins/``.
+
+.. __: writing_plugins.html
+
+Python modules
+''''''''''''''
+
+The Python modules in your toolkit should go in
+``gamera/my_toolkit/skeleton``.
+
+Building and installing a toolkit
+---------------------------------
+
+Building and installing toolkits is very similar to building and
+installing Gamera itself.  
+
+**You must ensure that Gamera is installed and working before
+attempting to build and install a Gamera toolkit.**
+
+The complete instructions for building Gamera toolkits is included in
+the skeleton example in the INSTALL file.  You should redistribute
+this file with your toolkit.

build/scripts-3.7/skeleton

@@ -0,0 +1,7 @@
+#!/usr/local/bin/python3.7
+
+# This just simply runs the skeleton toolkits main function
+
+from gamera.toolkits.skeleton import main
+
+main.main()

doc/gendoc.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python
+
+from gamera import gendoc
+
+if __name__ == '__main__':
+   # Step 1:
+   # Import all of the plugins to document.
+   # Be careful not to load the core plugins, or they
+   # will be documented here, too.
+   # If the plugins are not already installed, we'll just ignore
+   # them and generate the narrative documentation.
+   try:
+      from gamera.toolkits.skeleton.plugins import clear
+   except ImportError:
+      print "WARNING:"
+      print "This `skeleton` toolkit must be installed before generating"
+      print "the documentation.  For now, the system will skip generating"
+      print "documentation for the plugins."
+      print
+
+   # Step 2:
+   # Generate documentation for this toolkit
+   # This will handle any commandline arguments if necessary
+   gendoc.gendoc()