Exclude GTK/GObject methods [patch]

[Andi Albrecht]

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

[Daniel Haus]

Awesome theme, Andi!

As I don't use GTK at all, I have no personal opinion here. And
because it most likely won't cause any harm to anyone and is
switchable I will silently apply your patch as soon as I find the time
(in the next few days that is).

Thank you!

[Daniel Haus]

Your patch is applied in r46 (I did some slight modifications to
increase readability).

Thank you!

Am 03.03.2008 um 22:10 schrieb Andi Albrecht:

[Andi Albrecht]

Hi Daniel,

the last check is a little bit to restrictive. Somehow it removes
classmethods for classes subclassed from GObject, too. Here's a patch
to fix this.

Andi


Index: apydia/descriptors.py
===================================================================
--- . (revision 52)
+++ . (working copy)
@@ -350,7 +363,9 @@
and hasattr(value.__objclass__, "__gtype__"):
continue
if hasattr(value, "__class__") \
and value.__class__.__name__ == "GProps":
continue
- if "GObjectMeta" in repr(value): continue
+ if "GObjectMeta" in repr(value) \
+ and value not in self.value.__dict__.values():

+ continue
desc = create_desc(value, self.project)
desc.parent = self
results[key] = desc

On 5 Mrz., 09:05, Daniel Haus <daniel.h...@gmail.com> wrote:
> Your patch is applied in r46 (I did some slight modifications to
> increase readability).
>
> Thank you!
>
> Am 03.03.2008 um 22:10 schrieb Andi Albrecht:
>
> > 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.CFApplicatio...

[Daniel Haus]

Applied in r53.

Am 10.03.2008 um 12:16 schrieb Andi Albrecht:
> Hi Daniel,
>
> the last check is a little bit to restrictive. Somehow it removes
> classmethods for classes subclassed from GObject, too. Here's a patch
> to fix this.
>
> Andi

--
Daniel Haus
http://ematia.de

[Daniel Haus]

Thank you!