Basic vfunc support; Add fixed local toc menu and remove some unneede…

…d headlines

data/theme.patch

@@ -1,7 +1,7 @@
 diff -Nur sphinx_rtd_theme/breadcrumbs.html theme/breadcrumbs.html
---- sphinx_rtd_theme/breadcrumbs.html	2014-03-04 19:47:00.606021609 +0100
-+++ theme/breadcrumbs.html	2014-02-02 23:34:03.626687092 +0100
-@@ -6,13 +6,7 @@
+--- sphinx_rtd_theme/breadcrumbs.html	2014-03-05 00:38:28.311631703 +0100
++++ theme/breadcrumbs.html	2014-03-05 00:14:12.734943596 +0100
+@@ -6,14 +6,12 @@
        {% endfor %}
      <li>{{ title }}</li>
        <li class="wy-breadcrumbs-aside">
@@ -16,9 +16,14 @@ diff -Nur sphinx_rtd_theme/breadcrumbs.html theme/breadcrumbs.html
        </li>
    </ul>
    <hr/>
+ </div>
++
++<div class="local-toc">
++    {{ toc }}
++</div>
 diff -Nur sphinx_rtd_theme/layout.html theme/layout.html
---- sphinx_rtd_theme/layout.html	2014-03-04 19:47:00.606021609 +0100
-+++ theme/layout.html	2014-03-04 19:53:29.726220076 +0100
+--- sphinx_rtd_theme/layout.html	2014-03-05 00:38:28.311631703 +0100
++++ theme/layout.html	2014-03-05 00:27:20.963314565 +0100
 @@ -14,7 +14,13 @@
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -34,11 +39,38 @@ diff -Nur sphinx_rtd_theme/layout.html theme/layout.html
    {% endblock %}
 
    {# FAVICON #}
-@@ -25,6 +31,36 @@
+@@ -25,6 +31,63 @@
    {# CSS #}
    <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
 
 +<style>
++
++.local-toc {
++    display: none;
++}
++
++@media screen and (min-width: 768px){
++    .local-toc {
++        position:fixed;
++        right: 1em;
++        bottom: 1em;
++        display: block;
++    }
++
++    .local-toc li
++    {
++        display:block;
++        text-align:right;
++        padding:0.3em 0;
++        text-transform:uppercase;
++        font-size: 0.9em;
++    }
++}
++
++.wy-nav-content {
++    margin: 0 !important;
++}
++
 +.wy-side-nav-search, .wy-nav-top {
 +    background-color: #75507b !important;
 +}
@@ -71,7 +103,7 @@ diff -Nur sphinx_rtd_theme/layout.html theme/layout.html
    {# OPENSEARCH #}
    {% if not embedded %}
      {% if use_opensearch %}
-@@ -87,7 +123,7 @@
+@@ -87,7 +150,7 @@
        </div>
 
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">

data/theme/breadcrumbs.html

@@ -11,3 +11,7 @@
   </ul>
   <hr/>
 </div>
+
+<div class="local-toc">
+    {{ toc }}
+</div>

data/theme/layout.html

@@ -32,6 +32,33 @@
   <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
 
 <style>
+
+.local-toc {
+    display: none;
+}
+
+@media screen and (min-width: 768px){
+    .local-toc {
+        position:fixed;
+        right: 1em;
+        bottom: 1em;
+        display: block;
+    }
+
+    .local-toc li
+    {
+        display:block;
+        text-align:right;
+        padding:0.3em 0;
+        text-transform:uppercase;
+        font-size: 0.9em;
+    }
+}
+
+.wy-nav-content {
+    margin: 0 !important;
+}
+
 .wy-side-nav-search, .wy-nav-top {
     background-color: #75507b !important;
 }

pgi-docgen-build.py

@@ -78,3 +78,5 @@ def png_optimize_dir(dir_, pool_size=6):
             png_optimize_dir(dir_)
     else:
         print "optipng missing, skipping compression"
+
+    print "Done. See file://%s/index.html" % os.path.abspath(build_dir)

pgidocgen/enum.py

@@ -54,17 +54,15 @@ def write(self):
 """)
 
         for cls in classes:
-            title = util.make_rest_title(cls.__name__, "-")
             handle.write("""
-%s
 
 .. autoclass:: %s
     :show-inheritance:
     :members:
     :undoc-members:
     :private-members:
 
-""" % (title, cls.__module__ + "." + cls.__name__))
+""" % (cls.__module__ + "." + cls.__name__))
 
         for cls in classes:
             code = self._enums[cls]

pgidocgen/flags.py

@@ -56,8 +56,6 @@ def write(self):
 """)
 
         for cls in classes:
-            title = util.make_rest_title(cls.__name__, "^")
-            handle.write(title + "\n")
             if util.is_base(cls):
                 handle.write("""
 .. autoclass:: %s

pgidocgen/klass.py

@@ -24,6 +24,7 @@ def __init__(self, dir_, module_fileobj):
 
         self._classes = {}  # cls -> code
         self._methods = {}  # cls -> code
+        self._vfuncs = {}
         self._props = {}  # cls -> [prop]
         self._sigs = {}  # cls -> [sig]
 
@@ -44,6 +45,15 @@ def add_method(self, cls_obj, obj, code):
         else:
             self._methods[cls_obj] = [(obj, code)]
 
+    def add_vfunc(self, cls_obj, obj, code):
+        if isinstance(code, unicode):
+            code = code.encode("utf-8")
+
+        if cls_obj in self._vfuncs:
+            self._vfuncs[cls_obj].append((obj, code))
+        else:
+            self._vfuncs[cls_obj] = [(obj, code)]
+
     def add_properties(self, cls, props):
         assert cls not in self._props
 
@@ -107,12 +117,19 @@ def indent(c):
         # write the code
         for cls in classes:
             self._module.write(self._classes[cls])
-            methods = self._methods.get(cls, [])
 
             # sort static methods first, then by name
             def sort_func(e):
                 return util.is_normalmethod(e[0]), e[0].__name__
+
+            methods = self._methods.get(cls, [])[:]
             methods.sort(key=sort_func)
+
+            vfuncs = self._vfuncs.get(cls, [])[:]
+            vfuncs.sort(key=sort_func)
+
+            methods.extend(vfuncs)
+
             for obj, code in methods:
                 self._module.write(indent(code) + "\n")
 
@@ -172,6 +189,27 @@ def sort_func(e):
             for obj, code in methods:
                 h.write("    " + cls_name + "." + obj.__name__ + "\n")
 
+            # VFUNC
+
+            h.write("""
+Virtual Methods
+---------------
+
+""")
+
+            methods = self._vfuncs.get(cls, [])
+            if not methods:
+                h.write("None\n\n")
+            else:
+                h.write(".. autosummary::\n\n")
+
+            # sort static methods first, then by name
+            def sort_func(e):
+                return util.is_normalmethod(e[0]), e[0].__name__
+            methods.sort(key=sort_func)
+            for obj, code in methods:
+                h.write("    " + cls_name + "." + obj.__name__ + "\n")
+
             # PROPERTIES
 
             h.write("""
@@ -242,8 +280,8 @@ def sort_func(e):
                 self.write_field_table(cls, h)
 
             h.write("""
-Details
--------
+Class Details
+-------------
 """)
 
             if util.is_base(cls):

pgidocgen/module.py

@@ -130,10 +130,18 @@ def write(self):
                             continue
 
                         if callable(attr_obj):
-                            func_key = name + "." + attr
-                            code = repo.parse_function(func_key, obj, attr_obj)
-                            if code:
-                                class_gen.add_method(obj, attr_obj, code)
+                            if not util.is_virtualmethod(attr_obj):
+                                func_key = name + "." + attr
+                                code = repo.parse_function(
+                                    func_key, obj, attr_obj)
+                                if code:
+                                    class_gen.add_method(obj, attr_obj, code)
+                            else:
+                                func_key = name + "." + attr
+                                code = repo.parse_function(
+                                    func_key, obj, attr_obj)
+                                if code:
+                                    class_gen.add_vfunc(obj, attr_obj, code)
 
                 elif util.is_flags(obj):
                     code = repo.parse_flags(name, obj)

pgidocgen/namespace.py

@@ -231,35 +231,37 @@ def _parse_docs(dom):
     signals = {}
     properties = {}
     fields = {}
-
-    tag_names = {
-        ("glib:signal",): signals,
-        ("field",): fields,
-        ("property",): properties,
-        ("parameter", "glib:signal"): sparas,
-        ("parameter", "function"): parameters,
-        ("parameter", "method"): parameters,
-        ("parameter", "callback"): parameters,
-        ("parameter", "constructor"): parameters,
-        ("instance-parameter", "method"): parameters,
-        ("return-value", "callback"): returns,
-        ("return-value", "method"): returns,
-        ("return-value", "function"): returns,
-        ("return-value", "constructor"): returns,
-        ("return-value", "glib:signal"): sreturns,
-        ("interface",): all_,
-        ("method",): all_,
-        ("function",): all_,
-        ("constant",): all_,
-        ("record",): all_,
-        ("enumeration",): all_,
-        ("member",): all_,
-        ("callback",): all_,
-        ("alias",): all_,
-        ("constructor",): all_,
-        ("class",): all_,
-        ("bitfield",): all_,
-    }
+    vfuncs = {}
+
+    tag_names = [
+        [("glib:signal",), signals],
+        [("field",), fields],
+        [("property",), properties],
+        [("parameter", "glib:signal"), sparas],
+        [("parameter", "function"), parameters],
+        [("parameter", "method"), parameters],
+        [("parameter", "callback"), parameters],
+        [("parameter", "constructor"), parameters],
+        [("instance-parameter", "method"), parameters],
+        [("return-value", "callback"), returns],
+        [("return-value", "method"), returns],
+        [("return-value", "function"), returns],
+        [("return-value", "constructor"), returns],
+        [("return-value", "glib:signal"), sreturns],
+        [("interface",), all_],
+        [("method",), all_],
+        [("function",), all_],
+        [("constant",), all_],
+        [("record",), all_],
+        [("enumeration",), all_],
+        [("member",), all_],
+        [("callback",), all_],
+        [("alias",), all_],
+        [("constructor",), all_],
+        [("class",), all_],
+        [("bitfield",), all_],
+        [("virtual-method",), all_],
+    ]
 
     def get_child_by_tag(node, tag_name):
         for sub in node.childNodes:
@@ -272,7 +274,7 @@ def get_child_by_tag(node, tag_name):
     path_seen = set()
     path_done = set()
 
-    for target, result in tag_names.items():
+    for target, result in tag_names:
         tag = target[0]
         needed = target[1:]
 
@@ -284,7 +286,10 @@ def get_child_by_tag(node, tag_name):
             deprecated_version = e.getAttribute("deprecated-version")
 
             def get_name(elm):
-                return elm.getAttribute("name") or elm.getAttribute("glib:name")
+                n = elm.getAttribute("name") or elm.getAttribute("glib:name")
+                if elm.tagName == "virtual-method":
+                    n = "do_" + n
+                return n
 
             l = []
             tags = []
@@ -318,7 +323,10 @@ def get_name(elm):
             new = (docs, version, deprecated_version, deprecated)
             # Atspi-2.0 has some things declared twice, so
             # don't be too strict here.
-            assert key not in result or new == result[key], key
+
+            # We prefix vfuncs with "do_", but this could still clash here
+            if tag != "virtual-method":
+                assert key not in result or new == result[key], key
             result[key] = new
 
     # print path_seen - path_done

pgidocgen/util.py

@@ -239,6 +239,12 @@ def is_classmethod(obj):
         return False
 
 
+def is_virtualmethod(obj):
+    assert callable(obj)
+
+    return getattr(obj, "_is_virtual", False)
+
+
 def is_normalmethod(obj):
     return not is_staticmethod(obj) and not is_classmethod(obj)
 

tests/test_repo.py

@@ -52,6 +52,12 @@ def test_returns(self):
         ret = repo.lookup_return_docs("Gio.File.load_contents_finish")
         self.assertTrue(ret.strip())
 
+    def test_vfuns(self):
+        repo = Repository("Gtk", "3.0")
+
+        ret = repo.lookup_attr_docs("Gtk.TreeModel.do_get_iter")
+        self.assertTrue(ret.strip())
+
     def test_other(self):
         Repository("GLib", "2.0")
         Repository("GObject", "2.0")