From 8976c90f8565b70b6f6ecfebdf3f04e7e812e698 Mon Sep 17 00:00:00 2001 From: John Finlay Date: Wed, 19 Jul 2006 09:49:56 +0000 Subject: Output xref links for unknown links. * docs/xsl/html.xsl: Output xref links for unknown links. * docs/xsl/ref-html-style.xsl: Include refsect1 and refsect2 in indexed items but only ig they have ids. * configure.ac (AC_CONFIG_FILES) : Add docs/reference/version.xml * docs/reference/pygobject-ref.xml: Add pygobject-introduction.xml and version and builddate entities. Remove commented out items. * docs/Makefile.am: Add reference/pygobject-introduction.xml and reference/version.xml.in --- docs/reference/pygobject-introduction.xml | 239 ++++++++++++++++++++++++++++++ docs/reference/pygobject-ref.xml | 141 ++---------------- docs/reference/version.xml.in | 1 + 3 files changed, 252 insertions(+), 129 deletions(-) create mode 100644 docs/reference/pygobject-introduction.xml create mode 100644 docs/reference/version.xml.in (limited to 'docs/reference') diff --git a/docs/reference/pygobject-introduction.xml b/docs/reference/pygobject-introduction.xml new file mode 100644 index 0000000..a139646 --- /dev/null +++ b/docs/reference/pygobject-introduction.xml @@ -0,0 +1,239 @@ + + + + + Introduction + + This document describes many of the PyGObject + version 2.12 classes and their methods and associated + functions. Deprecated classes, functions and methods have been + specifically left out of this reference though classes that have become + deprecated since PyGObject 2.0 have been left in but annotated with a + deprecation warning. I have attempted to document as much of the + PyGObject API as I can but there are + undoubtedly errors and omissions. If you discover any of these please send + me email at finlay@moeraki.com or file + a bug report at bugzilla.gnome.org for the + pygobject project. Specific areas that have not been + documented include: + + + + The GParamSpec class + + + + This reference describes the API for PyGObject as + of version 2.11.0+ and assumes that the additional API changes for version + 2.12 will not be significant. There will undoubtedly be changes that are + not reflected in this reference. The differences in the API between + version 2.0 and previous versions are denoted in this reference with a + Note that describes the availability of the object, constructor, method or + function. Any of these that do not have a notation can be assumed to be + available in all versions of PyGObject from 2.0 and up. The source code + must be consulted if this reference and your version of + PyGObject seem to differ. You are encouraged to use the + latest version of PyGObject that is available. See the + PyGTK + homepage for more information and more resources on how to use + PyGObject as well as help in its development. + + The Reference contains a chapter for each + PyGObject module containing the class descriptions. The + class descriptions are arranged alphabetically within the + chapters. Currently there is one module chapter: + + + + The gobject module + The classes that are included in the +gobject module of PyGObject and are +accessed similar to: gobject.GObject. These classes are the base object +classes that the gtk and gtk.gdk +module classes are built on. + + + + + + + + Reference Page Format + + Each PyGObject class is described in a reference +page that has a number of sections in a fixed format. Each reference page +will have a subset of the following sections: + + + + Name + + The name and a one-line description of the +class. + + + + Synopsis + + A synopsis of the class and its methods and +optionally a list of associated functions. + + + + Ancestry + + The list of the parent classes of the class. This +section may not be present in all class descriptions. + + + + Properties + + A list of the properties (internal state) +supported by the class. This section may not be present in all classes. The +property descriptions include the name, the access operations (e.g. Read, +Write), and a brief description. Properties are accessed using the gobject.set_property() +and gobject.get_property() +methods that are available to every PyGObject object. This +section may not be present in all class descriptions. + + + + Attributes + + A set of internal object state data accessible as Python + attributes (e.g. object.attr). The attribute descriptions include + a name by which the attribute data is accessed, the access mode + (e.g. Read, Write), and a brief description of the attribute. Most + PyGObject classes do not support attributes so + this section is not present in most class descriptions. + + + + Signal Prototypes + + A list of the signals supported by the class including + the signal name and a synopsis of the signal handler function + prototype. This section may not be present in all class + descriptions. + + + + Description + A description of the class and possibly some of + the methods supported by the class. + + + + Constructor + + The description of the class object constructor including + the synopsis with brief parameter descriptions and a description + of th use of the constructor. There may be more than one + constructor description if the constructor supports different + parameter lists. This section may not be present in all class + descriptions. + + + + Methods + + A list of methods supported by the class. Each method + description includes: a synopsis of the method and its parameters + as well as a brief description of each parameter and return value + (if any); and, a description of the use of the method. + + + + Functions + + A list of related functions. Each function description + includes a synopsis of the function and its parameters and return + value (if any), and a description of the use of the + function. + + + + Signals + + A list of signals including a synopsis of the signal + handler prototype function with its parameters and return value + (if any). The signal emission conditions are briefly + described. This section is not present in all class descriptions; + specifically, the gtk.gdk classes do not + usually support signals. + + + + + The function and method synopsis parameters are displayed in + bold to denote Python keyword + parameters. Also if the parameter is optional its default value will be + displayed. For example the gobject.signal_lookup() + function synopsis is: + + + + gobject.signal_lookup + name + type + + + + The parameters name and + type are keyword parameters that can be specified + in a call either by position or keyword (in which case position is not + important). The following calls have the same result: + + + id = gobject.signal_lookup("clicked", gtk.Button) + id = gobject.signal_lookup("clicked", type=gtk.Button) + id = gobject.signal_lookup(name="clicked", type=gtk.Button) + id = gobject.signal_lookup(type=gtk.Button, name="clicked") + + + Parameters that are not keyword parameters are displayed in +italic and must be specified positionally but may also +be optional. + + + + + Copyright and License Notice + + The PyGObject 2.0 Reference is Copyright (C) 2004-2006 John + Finlay. + + This work is licensed under the Creative Commons + Attribution-ShareAlike License. To view a copy of this license, visit + http://creativecommons.org/licenses/by-sa/1.0/ + or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, + California 94305, USA. + + + + diff --git a/docs/reference/pygobject-ref.xml b/docs/reference/pygobject-ref.xml index 9252ea0..c455145 100644 --- a/docs/reference/pygobject-ref.xml +++ b/docs/reference/pygobject-ref.xml @@ -1,13 +1,15 @@ + ]> - + - July 6, 2006 + &builddate; PyGObject Reference Manual - for version 2.12.x - Version 2.11.0 + for version &version; + for PyGObject version &version; John @@ -18,137 +20,18 @@ This reference describes the classes of the python gobject module. - - + + + + Index + +--> diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in new file mode 100644 index 0000000..a24f987 --- /dev/null +++ b/docs/reference/version.xml.in @@ -0,0 +1 @@ +@PACKAGE_VERSION@ -- cgit