Let ontology inherit some properties from module if needed

Signed-off-by: Jan Pokorný <jpokorny@redhat.com>

3 files changed, 55 insertions, 23 deletions

diff --git a/ontogen.py b/ontogen.py
index c5c3ff2..d43ed1b 100644
--- a/ontogen.py
+++ b/ontogen.py
@@ -3,13 +3,12 @@
 # Author: Jan Pokorný <jpokorny at redhat dot com>
 # Licensed under LGPL v2.1 (the same as original ns-schema.xsl)
 
-from sys import stdout, stderr
+from sys import modules, stdout, stderr
 from datetime import date
 from textwrap import TextWrapper, dedent
 from os import extsep, getcwd, mkdir, symlink, remove
-from os.path import basename, dirname, exists, isdir, isfile, islink, join, \
-                    splitext, sep as pathsep
-from shutil import copy2 as copy
+from os.path import basename, dirname, exists, isdir, islink, join, splitext, \
+                    sep as pathsep
 from subprocess import call
 from shlex import split
 #import codecs
@@ -51,14 +50,17 @@ class ClassProperty(property):
 
 # another common fixer (adjusted): http://stackoverflow.com/a/13937525
 class InheritDocstring(type):
+    """Allows docstrings to be inherited (restricted to external classes)"""
     def __init__(this, name, bases, attrs):
-        if not getattr(this, '__doc__', None):
-            this.__doc__ = super(this, this).__doc__
+        if __name__ not in (this.__module__, this.__base__.__module__):
+            if not getattr(this, '__doc__', None):
+                this.__doc__ = super(this, this).__doc__
         super(InheritDocstring, InheritDocstring).__init__(this, name,
                                                            bases, attrs)
 
 
 def custom_symlink(source, link_name, report=False):
+    """symlink + overwriting (unlink-new) of existing symlinks"""
     if exists(link_name):
         if islink(link_name):
             remove(link_name)
@@ -101,6 +103,7 @@ class Example(object):
 class ExampleSelfFigureProto(type):
     def __new__(self, ontology):
         base = ontology.base
+
         class ExampleSelfFigure(Example):
             """Illustrative figure of the vocabulary"""
             image_full = ontology.version + VERSIONSEP + base + extsep + 'svg'
@@ -132,8 +135,13 @@ class RDFEntity(object):
 
     @ClassProperty
     @classmethod
+    def documentation(this):
+        return this.__doc__
+
+    @ClassProperty
+    @classmethod
     def label(this):
-        return '\n'.join(this.__doc__.strip().splitlines()[:1]).strip()
+        return '\n'.join(this.documentation.strip().splitlines()[:1]).strip()
 
     @ClassProperty
     @classmethod
@@ -143,7 +151,7 @@ class RDFEntity(object):
                 twd,
                 '\n'.join(map(
                     str.rstrip,
-                    this.__doc__.strip().splitlines()[2:])).split('\n\n')
+                    this.documentation.strip().splitlines()[2:])).split('\n\n')
             )
         )
 
@@ -229,11 +237,22 @@ class Ontology(RDFEntity):
             log.warning('{0} already has priorVersion set'.format(onto))
         return onto
 
+    # members - override
+
+    @ClassProperty
+    @classmethod
+    def documentation(this):
+        ret = getattr(this, '__doc__', '') or modules[this.__module__].__doc__
+        return ret
+
     # members
 
     @ClassProperty
     @classmethod
     def base_uri(this):
+        module = modules[this.__module__]
+        if hasattr(module, 'base_uri'):
+            return module.base_uri
         raise NotImplementedError
 
     @ClassProperty
@@ -256,6 +275,9 @@ class Ontology(RDFEntity):
     @ClassProperty
     @classmethod
     def creator(this):
+        module = modules[this.__module__]
+        if hasattr(module, '__author__'):
+            return module.__author__
         return ''
 
     @ClassProperty
@@ -325,6 +347,7 @@ class Ontology(RDFEntity):
 
     @classmethod
     def gendoc(this, infile, outfile, template=TEMPLATE_XSLT):
+        """Generate HTML as per RDF (ns-schema.xsl wrapper)"""
         cmd = 'xsltproc --stringparam xmlfile {reference} -o {outfile}' \
               ' {template} {infile}'.format(
                   reference=basename(infile),
@@ -339,6 +362,7 @@ class Ontology(RDFEntity):
 
     @classmethod
     def generate(this, ontologies=(), template=None, outfile='-', gendoc=True):
+        """Generate RDF as per declarations"""
         from genshi.template import MarkupTemplate
 
         namespaces = {}
@@ -383,10 +407,10 @@ class Ontology(RDFEntity):
                 custom_symlink(htmlfile, splitext(symfile)[0] + extsep + 'html',
                                'html')
                 for ex in [e for e in this.examples if e.image]:
+                    img = ex.image
                     if ex.__name__ == 'ExampleSelfFigure':
                         custom_symlink(ex.image_full, ex.symlink, 'self-figure')
                     elif not pathsep in img:
-                        img = ex.image
                         custom_symlink(join(this.base, img), img, 'image')
 
         if outobj is not stdout:
@@ -398,14 +422,17 @@ class Ontology(RDFEntity):
 
 
 class PrependFigure(InheritDocstring):
+    """Attaches self-figure (to be provided externally) as a first example"""
     def __new__(this, name, bases, attrs):
         ret = super(PrependFigure, PrependFigure).__new__(this, name, bases,
                                                           attrs)
+        if attrs['__module__'] == __name__:
+            return ret  # nothing more to do here for internal classes
         try:
             if all(map(lambda x: isinstance(x, basestring),
-                map(lambda x: getattr(ret, x, None),
-                    ('base', 'version')))
-            ) or True:
+                       map(lambda x: getattr(ret, x, None),
+                           ('base', 'version'))
+            )):
                 setattr(ret, 'examples', [ExampleSelfFigureProto(ret)]
                                          + list(getattr(ret, 'examples', ())))
         except NotImplementedError:
diff --git a/quickstart/README b/quickstart/README
index 9f74a11..bfd57ee 100644
--- a/quickstart/README
+++ b/quickstart/README
@@ -2,6 +2,10 @@ The "ontogen" symlink mimics the git submodule within consuming repo.
 
 When using this subdir as a start point for a new project, follow this:
 
-$ rm -rf ontogen
-$ git submodule add git://fedorapeople.org/home/fedora/jpokorny/public_git/ontogen.git
-$ for f in Makefile, .gitignore do; ln -s {ontogen/quickstart/,}.$f; done
+$ ONTOGENREPO=git://fedorapeople.org/home/fedora/jpokorny/public_git/ontogen.git
+$ PREFIX=$(basename $(pwd))
+$ git submodule add "${ONTOGENREPO}"
+$ for f in Makefile .gitignore; do ln -s {ontogen/quickstart/,}$f; done
+$ cat ontogen/quickstart/template.py \
+    | sed "s|template|${PREFIX}|g"   \
+    > ${PREFIX}.py
diff --git a/quickstart/template.py b/quickstart/template.py
index ead6874..eaa1669 100755
--- a/quickstart/template.py
+++ b/quickstart/template.py
@@ -1,5 +1,12 @@
 #!/usr/bin/env python
 # Example quickstart template for designing new ontologies
+"""Descriptive vocabulary for foos
+
+This vocabulary serves a purpose of shedding light into semantics
+in the field of foos.
+"""
+__author__ = 'John Doe'
+
 
 from sys import argv
 #from genshi.input import XML
@@ -10,7 +17,7 @@ from ontogen.ontogen import Property, Class, Example, OntologyWithFigure, \
 #from ontogen.ontogen import log
 #log.setLevel('DEBUG')
 
-BASE = 'http://example.org/net/template'
+base_uri = 'http://example.org/net/template'
 
 
 #
@@ -74,16 +81,10 @@ ontologies = Ontologies()
 
 
 class template(OntologyWithFigure):
-    """Descriptive vocabulary for foos
-
-    This vocabulary serves a purpose of shedding light into semantics
-    in the field of foos.
-    """
-    base_uri = BASE
     #creator = XML('''\
     #    <dc:X xmlns:dc="http://purl.org/dc/elements/1.1/"
     #    >John Doe</dc:X>''')
-    creator = 'John Doe'
+    pass
 
 
 @ontologies.include