diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..8d644aa --- /dev/null +++ b/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. + diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..8651f7f --- /dev/null +++ b/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) diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..9044a50 --- /dev/null +++ b/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 diff --git a/PKG-INFO b/PKG-INFO new file mode 100644 index 0000000..0ddc011 --- /dev/null +++ b/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 diff --git a/README b/README new file mode 100644 index 0000000..8035cad --- /dev/null +++ b/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. diff --git a/build/scripts-3.7/skeleton b/build/scripts-3.7/skeleton new file mode 100755 index 0000000..a44eaf1 --- /dev/null +++ b/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() diff --git a/doc/gendoc.py b/doc/gendoc.py new file mode 100644 index 0000000..5b6c5a2 --- /dev/null +++ b/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() diff --git a/doc/src/default.css b/doc/src/default.css new file mode 100644 index 0000000..fdbdb32 --- /dev/null +++ b/doc/src/default.css @@ -0,0 +1,530 @@ +@import url(html4css1.css); +@import url(pygments.css); + +body { + margin: 2em 2em 2em 2em; + background-color: #effffd; +} + +a.toc-backref { + text-decoration: none ; + color: black } + +h1 { + background-color: #e1f0ee; + color: #29493c; + border-top-color: #72ada8; + border-top-style: solid; + border-top-width: 4px +} + +h2 { + background-color: #e1f0ee; + color: #29493c; + border-top-color: #72ada8; + border-top-style: solid; + border-top-width: 2px +} + +h3 { + background-color: #e1f0ee; + color: #29493c; + border-top-color: #72ada8; + border-top-style: solid; + border-top-width: 1px +} + +h4 { + background-color: #e1f0ee; + color: #29493c; + border-top-color: #72ada8; + border-top-style: solid; + border-top-width: 1px +} + +h5 { + background-color: #e1f0ee; + color: #29493c; + border-top-color: #72ada8; + border-top-style: solid; + border-top-width: 0.5px +} + +div.code-block, div.highlight { +margin-left: 2em; +margin-right: 2em; +background-color: #f0f0e0; +font-family: "Andale Mono", "Bitstream Vera Sans Mono", monospace; +border-color: #e0e0d0; +border-style: solid; +border-width: 1px; +font-size: 10pt; +padding: 1em; +} + +/* The following is for SilverCity syntax highlighting */ + + +.code_default +{ + FONT-FAMILY: "Andale Mono", "Bitstream Vera Sans Mono", monospace; + FONT-SIZE: 10pt; +} + +.c_character +{ + color: olive; +} + +.c_comment +{ + color: green; + font-style: italic; +} + +.c_commentdoc +{ + color: green; + font-style: italic; +} + +.c_commentdockeyword +{ + color: navy; + font-weight: bold; +} + +.c_commentdockeyworderror +{ + color: red; + font-weight: bold; +} + +.c_commentline +{ + color: green; + font-style: italic; +} + +.c_commentlinedoc +{ + color: green; + font-style: italic; +} + +.c_default +{ +} + +.c_identifier +{ + color: black; +} + +.c_number +{ + color: #009999; +} + +.c_operator +{ + color: black; +} + +.c_preprocessor +{ + color: navy; + font-weight: bold; +} + +.c_regex +{ + color: olive; +} + +.c_string +{ + color: olive; +} + +.c_stringeol +{ + color: olive; +} + +.c_uuid +{ + color: olive; +} + +.c_verbatim +{ + color: olive; +} + +.c_word +{ + color: navy; + font-weight: bold; +} + +.c_word2 +{ + color: navy; + font-weight: bold; +} + +.h_asp +{ + color: #ffff00; +} + +.h_aspat +{ + color: #ffdf00; +} + +.h_attribute +{ + color: #008080; +} + +.h_attributeunknown +{ + color: #ff0000; +} + +.h_cdata +{ + color: #ffdf00; +} + +.h_comment +{ + color: #808000; +} + +.h_default +{ +} + +.h_doublestring +{ + color: olive; +} + +.h_entity +{ + color: #800080; +} + +.h_number +{ + color: #009999; +} + +.h_other +{ + color: #800080; +} + +.h_script +{ + color: #000080; +} + +.h_singlestring +{ + color: olive; +} + +.h_tag +{ + color: #000080; +} + +.h_tagend +{ + color: #000080; +} + +.h_tagunknown +{ + color: #ff0000; +} + +.h_xmlend +{ + color: #0000ff; +} + +.h_xmlstart +{ + color: #0000ff; +} + +.pl_array +{ + color: black; +} + +.pl_backticks +{ + color: olive; +} + +.pl_character +{ + color: olive; +} + +.pl_commentline +{ + color: green; + font-style: italic; +} + +.pl_datasection +{ + color: olive; +} + +.pl_default +{ +} + +.pl_error +{ + color: red; + font-weight: bold; +} + +.pl_hash +{ + color: black; +} + +.pl_here_delim +{ + color: olive; +} + +.pl_here_q +{ + color: olive; +} + +.pl_here_qq +{ + color: olive; +} + +.pl_here_qx +{ + color: olive; +} + +.pl_identifier +{ + color: black; +} + +.pl_longquote +{ + color: olive; +} + +.pl_number +{ + color: #009999; +} + +.pl_operator +{ + color: black; +} + +.pl_pod +{ + color: black; + font-style: italic; +} + +.pl_preprocessor +{ + color: navy; + font-weight: bold; +} + +.pl_punctuation +{ + color: black; +} + +.pl_regex +{ + color: olive; +} + +.pl_regsubst +{ + color: olive; +} + +.pl_scalar +{ + color: black; +} + +.pl_string +{ + color: olive; +} + +.pl_string_q +{ + color: olive; +} + +.pl_string_qq +{ + color: olive; +} + +.pl_string_qr +{ + color: olive; +} + +.pl_string_qw +{ + color: olive; +} + +.pl_string_qx +{ + color: olive; +} + +.pl_symboltable +{ + color: black; +} + +.pl_word +{ + color: navy; + font-weight: bold; +} + +.p_character +{ + color: olive; +} + +.p_classname +{ + color: blue; + font-weight: bold; +} + +.p_commentblock +{ + color: gray; + font-style: italic; +} + +.p_commentline +{ + color: green; + font-style: italic; +} + +.p_default +{ +} + +.p_defname +{ + color: #009999; + font-weight: bold; +} + +.p_identifier +{ + color: black; +} + +.p_number +{ + color: #009999; +} + +.p_operator +{ + color: black; +} + +.p_string +{ + color: olive; +} + +.p_stringeol +{ + color: olive; +} + +.p_triple +{ + color: olive; +} + +.p_tripledouble +{ + color: olive; +} + +.p_word +{ + color: navy; + font-weight: bold; +} + +.yaml_comment +{ + color: #008800; + font-style: italic; +} + +.yaml_default +{ +} + +.yaml_document +{ + color: #808080; + font-style: italic; +} + +.yaml_identifier +{ + color: navy; + font-weight: bold; +} + +.yaml_keyword +{ + color: #880088; +} + +.yaml_number +{ + color: #880000; +} + +.yaml_reference +{ + color: #008888; +} + diff --git a/doc/src/html4css1.css b/doc/src/html4css1.css new file mode 100644 index 0000000..2c68fbd --- /dev/null +++ b/doc/src/html4css1.css @@ -0,0 +1,287 @@ +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Date: $Date: 2007/08/10 14:44:25 $ +:Revision: $Revision: 1.1 $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left { + clear: left } + +img.align-right { + clear: right } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em; + background-color: #f7fffd; + border-color: #72ada8; + border: solid thin #aaaaaa; +} + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; +} + +td.field-body, th.field-name { + padding: 0.5em; + border: solid thin #aaaaaa; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +tt.docutils { } + +ul.auto-toc { + list-style-type: none } diff --git a/doc/src/images/turtle.jpg b/doc/src/images/turtle.jpg new file mode 100644 index 0000000..19751f7 Binary files /dev/null and b/doc/src/images/turtle.jpg differ diff --git a/doc/src/index.txt b/doc/src/index.txt new file mode 100644 index 0000000..61964c7 --- /dev/null +++ b/doc/src/index.txt @@ -0,0 +1,124 @@ +================================ +Overview of the skeleton toolkit +================================ + +This is just an example +''''''''''''''''''''''' + +This document is a high-level overview of the skeleton toolkit, that +you will eventually want to replace with documentation of your own. + +It's a good idea in the narrative documentation to provide a link to +the generated plugin method documentation like this_. + +.. _this: plugins.html + +Documenting toolkits +'''''''''''''''''''' + +To document a toolkit using the Gamera documentation system, the +author should perform three steps: 1) write narrative documentation, +2) write plugin method documentation, and 3) create a documentation +generation script. + +Writing narrative documentation +``````````````````````````````` + +The narrative documentation is intended for longer "how-to" like documents. + +Put narrative or high-level documentation in ``doc/src/``, in ``.txt`` +files in reStructuredText_ format. Each ``.txt`` file will be +converted into a corresponding ``.html`` when the documentation is +generated. + +.. _reStructuredText: http://docutils.sf.net/ + +Optionally, any inline images to be included can be placed in +``doc/src/images/``. For example: + +.. image:: turtle.jpg + +Plugin documentation +```````````````````` + +Document each plugin method in its Python docstring. This docstring +should occur on the line following the ``class`` statement where each +``PluginFunction`` is defined. + +Optionally, write a documentation example. This is a snippet of code +that will be run to generate an image that demonstrates the +capabilities of the plugin function. + +These steps are described in greater detail in the `writing plugins`__ +chapter. + +.. __: writing_plugins.html#documenting-plugin-functions + +Documentation generation script +``````````````````````````````` + +A small script is required that loads the toolkits' plugins and then +calls out to the Gamera documentation system. The example +documentation generation script included in the skeleton toolkit +example is as follows: + +.. code:: Python + + #!/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() + +Building the documentation +`````````````````````````` + +Once these three elements are in place, 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. + diff --git a/doc/src/pygments.css b/doc/src/pygments.css new file mode 100755 index 0000000..901c83f --- /dev/null +++ b/doc/src/pygments.css @@ -0,0 +1,61 @@ +.hll { background-color: #ffffcc } +.c { color: #408080; font-style: italic } /* Comment */ +.err { border: 1px solid #FF0000 } /* Error */ +.k { color: #008000; font-weight: bold } /* Keyword */ +.o { color: #666666 } /* Operator */ +.cm { color: #408080; font-style: italic } /* Comment.Multiline */ +.cp { color: #BC7A00 } /* Comment.Preproc */ +.c1 { color: #408080; font-style: italic } /* Comment.Single */ +.cs { color: #408080; font-style: italic } /* Comment.Special */ +.gd { color: #A00000 } /* Generic.Deleted */ +.ge { font-style: italic } /* Generic.Emph */ +.gr { color: #FF0000 } /* Generic.Error */ +.gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.gi { color: #00A000 } /* Generic.Inserted */ +.go { color: #808080 } /* Generic.Output */ +.gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.gt { color: #0040D0 } /* Generic.Traceback */ +.kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.kp { color: #008000 } /* Keyword.Pseudo */ +.kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.kt { color: #B00040 } /* Keyword.Type */ +.m { color: #666666 } /* Literal.Number */ +.s { color: #BA2121 } /* Literal.String */ +.na { color: #7D9029 } /* Name.Attribute */ +.nb { color: #008000 } /* Name.Builtin */ +.nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.no { color: #880000 } /* Name.Constant */ +.nd { color: #AA22FF } /* Name.Decorator */ +.ni { color: #999999; font-weight: bold } /* Name.Entity */ +.ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +.nf { color: #0000FF } /* Name.Function */ +.nl { color: #A0A000 } /* Name.Label */ +.nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.nt { color: #008000; font-weight: bold } /* Name.Tag */ +.nv { color: #19177C } /* Name.Variable */ +.ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.w { color: #bbbbbb } /* Text.Whitespace */ +.mf { color: #666666 } /* Literal.Number.Float */ +.mh { color: #666666 } /* Literal.Number.Hex */ +.mi { color: #666666 } /* Literal.Number.Integer */ +.mo { color: #666666 } /* Literal.Number.Oct */ +.sb { color: #BA2121 } /* Literal.String.Backtick */ +.sc { color: #BA2121 } /* Literal.String.Char */ +.sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.s2 { color: #BA2121 } /* Literal.String.Double */ +.se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +.sh { color: #BA2121 } /* Literal.String.Heredoc */ +.si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +.sx { color: #008000 } /* Literal.String.Other */ +.sr { color: #BB6688 } /* Literal.String.Regex */ +.s1 { color: #BA2121 } /* Literal.String.Single */ +.ss { color: #19177C } /* Literal.String.Symbol */ +.bp { color: #008000 } /* Name.Builtin.Pseudo */ +.vc { color: #19177C } /* Name.Variable.Class */ +.vg { color: #19177C } /* Name.Variable.Global */ +.vi { color: #19177C } /* Name.Variable.Instance */ +.il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/gamera/toolkits/skeleton/__init__.py b/gamera/toolkits/skeleton/__init__.py new file mode 100644 index 0000000..a84f435 --- /dev/null +++ b/gamera/toolkits/skeleton/__init__.py @@ -0,0 +1,34 @@ +""" +Toolkit setup + +This file is run on importing anything within this directory. +Its purpose is only to help with the Gamera GUI shell, +and may be omitted if you are not concerned with that. +""" + +from gamera import toolkit +import wx +from gamera.toolkits.skeleton import main + +# Let's import all our plugins here so that when this toolkit +# is imported using the "Toolkit" menu in the Gamera GUI +# everything works. + +from gamera.toolkits.skeleton.plugins import clear + +# You can inherit from toolkit.CustomMenu to create a menu +# for your toolkit. Create a list of menu option in the +# member _items, and a series of callback functions that +# correspond to them. The name of the callback function +# should be the same as the menu item, prefixed by '_On' +# and with all spaces converted to underscores. +class SkeletonMenu(toolkit.CustomMenu): + _items = ["Skeleton Toolkit", + "Skeleton Toolkit 2"] + def _OnSkeleton_Toolkit(self, event): + wx.MessageDialog(None, "You clicked on Skeleton Toolkit!").ShowModal() + main.main() + def _OnSkeleton_Toolkit_2(self, event): + wx.MessageDialog(None, "You clicked on Skeleton Toolkit 2!").ShowModal() + main.main() +skeleton_menu = SkeletonMenu() diff --git a/gamera/toolkits/skeleton/main.py b/gamera/toolkits/skeleton/main.py new file mode 100644 index 0000000..0890981 --- /dev/null +++ b/gamera/toolkits/skeleton/main.py @@ -0,0 +1,21 @@ +""" +The main function for the Skeleton Gamera toolkit + +This is a good place for top-level functions, such as things +that would be called from the command line. + +This module is not strictly necessary. +""" + +from time import sleep +from sys import stdout + +def main(): + """This is a top-level function for the toolkit. It doesn't +really do anything...""" + stdout.write("Processing (well, not really...)") + for i in range(5): + stdout.write(".") + stdout.flush() + sleep(1) + diff --git a/gamera/toolkits/skeleton/plugins/__init__.py b/gamera/toolkits/skeleton/plugins/__init__.py new file mode 100644 index 0000000..24609b3 --- /dev/null +++ b/gamera/toolkits/skeleton/plugins/__init__.py @@ -0,0 +1,4 @@ +# You need to have some sort of __init__.py file here +# in order to import modules in this directory. +# It is deliberately empty. + diff --git a/gamera/toolkits/skeleton/plugins/clear.py b/gamera/toolkits/skeleton/plugins/clear.py new file mode 100644 index 0000000..59ba13c --- /dev/null +++ b/gamera/toolkits/skeleton/plugins/clear.py @@ -0,0 +1,15 @@ +from gamera.plugin import * + +class clear(PluginFunction): + """Fills the entire image with white.""" + category = "Draw" + self_type = ImageType([ONEBIT, GREYSCALE, GREY16, FLOAT, RGB]) + +class ClearModule(PluginModule): + cpp_headers=["clear.hpp"] + cpp_namespace=["Gamera"] + category = "Skeleton" + functions = [clear] + author = "Your name here" + url = "Your URL here" +module = ClearModule() diff --git a/include/plugins/clear.hpp b/include/plugins/clear.hpp new file mode 100755 index 0000000..0d1f6e3 --- /dev/null +++ b/include/plugins/clear.hpp @@ -0,0 +1,19 @@ +#ifndef skeleton_fill_white +#define skeleton_fill_white + +#include "gamera.hpp" + +namespace Gamera { + + /* This is a very simple plugin that simply fills the image with white + + See the Gamera plugin documentation for more information on how to + write Gamera plugins. + */ + template + void clear(T& image) { + std::fill(image.vec_begin(), image.vec_end(), white(image)); + } +} + +#endif diff --git a/rename.py b/rename.py new file mode 100755 index 0000000..c9837d2 --- /dev/null +++ b/rename.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python + +from os import rename +from os.path import * +from sys import argv + + +def change_content(change_to, dirname, names): + for name in names: + full_path = join(dirname, name) + if isfile(full_path): + print("Adjusting content in %s" % full_path) + content = open(full_path, "r").read() + content = content.replace(change_from.capitalize(), change_to.capitalize()) + content = content.replace(change_from.upper(), change_to.upper()) + content = content.replace(change_from, change_to) + open(full_path, "w").write(content) + elif isdir(full_path): + walk(full_path, change_content, change_to) + + +def rename_files(change_to, dirname, names): + for name in names: + full_path = join(dirname, name) + if isdir(full_path): + walk(full_path, rename_files, change_to) + if name.find(change_from) != -1: + new_name = name.replace(change_from, change_to) + print("Renaming %s to %s" % (full_path, join(dirname, new_name))) + rename(full_path, join(dirname, new_name)) + + +change_from = 'skeleton' +change_to = argv[-1].lower() +print("Changing name of toolkit project to '%s'." % change_to) +walk(".", change_content, change_to) +walk(".", rename_files, change_to) diff --git a/scripts/skeleton b/scripts/skeleton new file mode 100755 index 0000000..dc9a855 --- /dev/null +++ b/scripts/skeleton @@ -0,0 +1,7 @@ +#!/usr/bin/env python + +# This just simply runs the skeleton toolkits main function + +from gamera.toolkits.skeleton import main + +main.main() diff --git a/setup.py b/setup.py new file mode 100755 index 0000000..f64756c --- /dev/null +++ b/setup.py @@ -0,0 +1,31 @@ +#!/usr/bin/env python + +from distutils.core import setup + +from gamera import gamera_setup + +# This constant should be the name of the toolkit +TOOLKIT_NAME = "skeleton" + +# ---------------------------------------------------------------------------- +# You should not usually have to edit anything below, but it is +# implemented here and not in the Gamera core so that you can edit it +# if you need to do something more complicated (for example, building +# and linking to a third- party library). +# ---------------------------------------------------------------------------- + +PLUGIN_PATH = 'gamera/toolkits/%s/plugins/' % TOOLKIT_NAME +PACKAGE = 'gamera.toolkits.%s' % TOOLKIT_NAME +PLUGIN_PACKAGE = PACKAGE + ".plugins" +plugins = gamera_setup.get_plugin_filenames(PLUGIN_PATH) +plugin_extensions = gamera_setup.generate_plugins(plugins, PLUGIN_PACKAGE) + +# This is a standard distutils setup initializer. If you need to do +# anything more complex here, refer to the Python distutils documentation. +setup(name=TOOLKIT_NAME, + version="3.0.1", + ext_modules=plugin_extensions, + packages=[PACKAGE, PLUGIN_PACKAGE], + scripts=['scripts/skeleton'], + requires=['gamera'] + )