zeitgeist team mailing list archive

[Markus Korn <thekorn@xxxxxx>]

Markus Korn has proposed merging lp:~thekorn/zeitgeist/fix-634055-ontology-docs into lp:zeitgeist.

Requested reviews:
  Zeitgeist Framework Team (zeitgeist)


Out ontology is now documented in a table format, which is a bit less pythonic than our old format and should be more readable (LP: #634055)

To view the new doc run:

make doc
gnome-open doc/zeitgeist/build/html/index.html

-- 
https://code.launchpad.net/~thekorn/zeitgeist/fix-634055-ontology-docs/+merge/35066
Your team Zeitgeist Framework Team is requested to review the proposed merge of lp:~thekorn/zeitgeist/fix-634055-ontology-docs into lp:zeitgeist.

=== modified file '.bzrignore'
--- .bzrignore	2010-06-25 22:34:58 +0000
+++ .bzrignore	2010-09-10 09:16:50 +0000
@@ -28,6 +28,7 @@
 zeitgeist-datahub
 doc/zeitgeist/build
 doc/zeitgeist/source/.static
+doc/zeitgeist/source/ontology.rst
 extra/ontology/*.py
 tools/cli/zeitgeist
 tools/gtk/zeitgeist

=== modified file 'doc/zeitgeist/Makefile'
--- doc/zeitgeist/Makefile	2009-12-14 09:18:11 +0000
+++ doc/zeitgeist/Makefile	2010-09-10 09:16:50 +0000
@@ -25,8 +25,9 @@
 
 clean:
 	rm -rf build/* source/.static
+	-rm source/ontology.rst
 
-init:
+init: ontology
 	mkdir -p build/changes build/doctrees source/.static
 
 html: init
@@ -69,3 +70,6 @@
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
 	@echo
 	@echo "The overview file is in build/changes."
+
+ontology:
+	python source/make_ontology.py > source/ontology.rst

=== modified file 'doc/zeitgeist/source/conf.py'
--- doc/zeitgeist/source/conf.py	2010-09-09 21:40:51 +0000
+++ doc/zeitgeist/source/conf.py	2010-09-10 09:16:50 +0000
@@ -191,44 +191,3 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/dev': None}
-
-from sphinx.ext.autodoc import Documenter
-from zeitgeist.datamodel import Symbol, StorageState, ResultType, EnumValue
-
-class SymbolDocumenter(Documenter):
-    
-    objtype = 'symbol'
-    member_order = 160
-    directivetype = "attribute"
-    
-    @classmethod
-    def can_document_member(cls, member, membername, isattr, parent):
-        # Symboldocumenter knows how to handle symbols and enums
-        return isinstance(parent, Documenter) and \
-            isinstance(member, (Symbol, EnumValue))
-        
-    def generate(self, more_content=None, real_modname=None,
-             check_module=False, all_members=False):
-        # for symbols we document per default all members
-        return Documenter.generate(self, more_content, real_modname, True, True)
-        
-    def resolve_name(self, modname, parents, path, base):
-        # we know where they are, so hardcode the import path
-        return "zeitgeist.datamodel", parents + [base,]
-        
-    def get_object_members(self, want_all):
-        # we want a special order for enums
-        r = Documenter.get_object_members(self, want_all)
-        if self.object in (ResultType, StorageState):
-            # we sort our enums by integer values
-            r = (r[0], sorted(r[1],  key=lambda x: x[1]))
-        elif isinstance(self.object, Symbol):
-            # we treat symbol objects special and only document their child
-            # symbols
-            return False, sorted((i.name, i) for i in self.object.get_children())
-        return r
-        
-        
-def setup(app):
-    app.add_autodocumenter(SymbolDocumenter)
-    

=== modified file 'doc/zeitgeist/source/datamodel.rst'
--- doc/zeitgeist/source/datamodel.rst	2010-04-19 19:55:01 +0000
+++ doc/zeitgeist/source/datamodel.rst	2010-09-10 09:16:50 +0000
@@ -19,12 +19,14 @@
 Interpretation
 ++++++++++++++
 
-.. autosymbol:: Interpretation
+A collection of class:`Symbol` objects which represents the interpretations
+defined by the zeitgeist ontology. For more information see :ref:`symbol-interpretation`.
 
 Manifestation
 +++++++++++++
 
-.. autosymbol:: Manifestation
+A collection of class:`Symbol` objects which represents the manifestations
+defined by the zeitgeist ontology. For more information see :ref:`symbol-manifestation`.
 
 TimeRange
 +++++++++

=== modified file 'doc/zeitgeist/source/index.rst'
--- doc/zeitgeist/source/index.rst	2010-06-10 21:54:05 +0000
+++ doc/zeitgeist/source/index.rst	2010-09-10 09:16:50 +0000
@@ -33,3 +33,11 @@
    :maxdepth: 2
    
    HACKING
+
+Ontology
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   ontology

=== added file 'doc/zeitgeist/source/make_ontology.py'
--- doc/zeitgeist/source/make_ontology.py	1970-01-01 00:00:00 +0000
+++ doc/zeitgeist/source/make_ontology.py	2010-09-10 09:16:50 +0000
@@ -0,0 +1,168 @@
+import sys
+import os.path
+import textwrap
+
+sys.path.insert(0, os.path.abspath('../..'))
+
+from zeitgeist.datamodel import Interpretation, Manifestation
+
+ROWS = ["Children", "Parent", "URI", "Description", "Python object"]
+
+PAGE_TEMPLATE = """\
+======================
+The Zeitgeist Ontology
+======================
+
+.. _symbol-interpretation:
+
+Interpretations
+===============
+
+%(interpretations)s
+
+.. _symbol-manifestation:
+
+Manifestations
+==============
+
+%(manifestations)s
+"""
+
+def make_line(pattern, columns):
+    result = "|"
+    for n, size in enumerate(pattern):
+        col = " "
+        col += columns[n]
+        col += " " *(size-len(col))
+        assert len(col) == size, "%r, %i != %i" %(col, len(col), size)
+        result += "%s|" %col
+    return result + "\n"
+    
+def _wrap_col(column):
+    for line in column:
+        if not line:
+            yield ""
+        else:
+            for wrapped_line in textwrap.wrap(line, 80):
+                yield wrapped_line
+
+def make_row(pattern, columns=None):
+    if columns is None:
+        result = "+"
+        for size in pattern:
+            result += "-"*size
+            result += "+"
+        result += "\n"
+    else:
+        result = ""
+        columns = [col.split("\n") for col in columns]
+        columns = [list(_wrap_col(col)) for col in columns]
+        max_rows = max(map(len, columns))
+        columns = [col + [""]*(max_rows-len(col)) for col in columns]
+        for line in zip(*columns):
+            result += make_line(pattern, line)
+    return result
+    
+def iter_col_width(col):
+    for row in col:
+        for line in row.split("\n"):
+            yield min(len(line), 80)
+
+def make_table_body(has_header=False, *columns):
+    width_pattern = []
+    check_rows = None
+    for col in columns:
+        width_pattern.append(max(iter_col_width(col)) + 2)
+        if check_rows is None:
+            check_rows = len(col)
+        else:
+            assert len(col) == check_rows, "all columns must have the same number of rows"
+    if has_header:
+        table = ""
+    else:
+        table = make_row(width_pattern)
+    for row in zip(*columns):
+        table += make_row(width_pattern, row)
+        table += make_row(width_pattern)
+    return table
+    
+def make_children(symbol):
+    children = symbol.get_children()
+    if not children:
+        return None
+    result = ""
+    for child in children:
+        result += ":ref:`symbol-%s`,\n" %child.uri.split("/")[-1].lower()
+    return result.strip().strip(",")
+    
+def get_one_parent(symbol):
+    parents = list(symbol.get_parents())
+    if parents:
+        return parents[0]
+    else:
+        return None
+    
+def make_python_path(symbol):
+    def _gen(sym):
+        yield sym.name
+        parent = get_one_parent(sym)
+        if parent:
+            for s in _gen(parent):
+                yield s
+    return "``zeitgeist.datamodel.%s``" %".".join(list(_gen(symbol))[::-1])
+    
+def doc_symbol(symbol, make_ref=True):
+    if make_ref:
+        result = ".. _symbol-%s:\n\n" %(symbol.uri.split("/")[-1].lower())
+    else:
+        result = ""
+    if symbol.display_name:
+        result += "%s\n" %symbol.display_name
+        result += "*" *len(symbol.display_name)
+        result += "\n\n"
+    parent = get_one_parent(symbol)
+    if parent:
+        parent = ":ref:`symbol-%s`" %parent.uri.split("/")[-1].lower()
+    result += make_table_body(False, ["**%s**" %r for r in ROWS], 
+        [make_children(symbol) or "--", parent or "--", symbol.uri, symbol.doc, make_python_path(symbol)]
+    )
+    return result
+    
+def gen_symbol_level(symbol, level=0):
+    def _gen(symb, lev):
+        for child in symb.get_children():
+            yield (lev, child.uri)
+            for c in _gen(child, lev+1):
+                yield c
+    children = list(_gen(symbol, level))
+    result = dict()
+    for n, uri in children:
+        result.setdefault(n, []).append(uri)
+    max_level = max(result)
+    return [result[n] for n in range(max_level+1)]
+
+def create_doc(template):
+    values = dict.fromkeys(["interpretations", "manifestations"], "")
+    values["interpretations"] += doc_symbol(Interpretation, False)
+    values["interpretations"] += "\n"
+    for level in gen_symbol_level(Interpretation):
+        for uri in sorted(level):
+            values["interpretations"] += doc_symbol(Interpretation[uri])
+            values["interpretations"] += "\n"
+
+    values["manifestations"] += doc_symbol(Manifestation, False)
+    values["manifestations"] += "\n"
+    for level in gen_symbol_level(Manifestation):
+        for uri in sorted(level):
+            values["manifestations"] += doc_symbol(Manifestation[uri])
+            values["manifestations"] += "\n"
+    return template %values
+
+if __name__ == "__main__":
+    if len(sys.argv) == 1:
+        template = PAGE_TEMPLATE
+    elif len(sys.argv) == 2:
+        template = file(sys.argv[1]).read()
+    else:
+        raise ValueError
+    print create_doc(template)