Hi,
I've got some troubles today documenting a PyGTK-based project. The
problem is that there are a lot of GObject and gtk widget subclasses
in this project and apydia documents all inherited methods. Generally
it's a good thing to have an almost complete API documentation, but I
don't want to document about a hundred methods for each class, that an
API user either never would use or where he knows where a proper
documentation for these methods can be found.
So I've wrote a patch that adds an "exclude_gtk" option. If this
option is set, all inherited gtk/GObject methods are supressed -
except the ones that are overwritten.
Here is an example of both versions:
exclude_gtk flag set:
http://cf.andialbrecht.de/api/test/api_excludegtk/cf.app.CFApplication.html
exclude_gtk flag not set:
http://cf.andialbrecht.de/api/test/api_withgtk/cf.app.CFApplication.html
CFApplication inherits in this case from bonobo.Application; don't
mind the docstrings, I'm migrating from epydoc... ;-)
In my opinion, a documentation without that bunch of standard gtk/
GObject methods is much more readable than with them. btw, an
additional inheritance graph would make it clear for an advanced user
which additional methods are present.
So, here's the patch. What do you think about it?
Andi
Index: apydia/command.py
===================================================================
--- . (revision 45)
+++ . (working copy)
@@ -47,7 +47,9 @@
open = Boolean("o", "open generated files in browser when
done"),
config = Filename("c", "specify config file"),
verbose = Boolean("v", "be verbose"),
- apiprefix = String("p", "namespace prefix for generated api
files")
+ apiprefix = String("p", "namespace prefix for generated api
files"),
+ exclude_gtk = Boolean("g", "exclude GTK/GObject methods",
+ default=False)
)
def parse_config_file(self, options, args):
Index: apydia/descriptors.py
===================================================================
--- . (revision 45)
+++ . (working copy)
@@ -337,6 +337,14 @@
for key in keys:
try:
value = getattr(self.value, key)
+ if self.project.options.exclude_gtk:
+ if hasattr(value, "__gtype__") \
+ or (hasattr(value, "__objclass__") \
+ and hasattr(value.__objclass__, "__gtype__"))
\
+ or (hasattr(value, "__class__") \
+ and value.__class__.__name__ == "GProps") \
+ or "GObjectMeta" in repr(value):
+ continue
desc = create_desc(value, self.project)
desc.parent = self
results[key] = desc