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)
_______________________________________________ Mailing list: https://launchpad.net/~zeitgeist Post to : zeitgeist@lists.launchpad.net Unsubscribe : https://launchpad.net/~zeitgeist More help : https://help.launchpad.net/ListHelp