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
