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 --- ChangeLog | 15 ++ configure.ac | 1 + docs/Makefile.am | 12 +- docs/reference/pygobject-introduction.xml | 239 ++++++++++++++++++++++++++++++ docs/reference/pygobject-ref.xml | 141 ++---------------- docs/reference/version.xml.in | 1 + docs/xsl/common.xsl | 3 +- docs/xsl/html.xsl | 18 ++- docs/xsl/ref-html-style.xsl | 24 +-- 9 files changed, 308 insertions(+), 146 deletions(-) create mode 100644 docs/reference/pygobject-introduction.xml create mode 100644 docs/reference/version.xml.in diff --git a/ChangeLog b/ChangeLog index 0b213ad..c58a94d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2006-07-19 John Finlay + + * 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 + 2006-07-18 Johan Dahlin * docs/Makefile.am (HTMLdir): Install book in $datadir/gtk-doc/html diff --git a/configure.ac b/configure.ac index d317d75..f693cc6 100644 --- a/configure.ac +++ b/configure.ac @@ -128,6 +128,7 @@ AC_CONFIG_FILES( Makefile pygobject-2.0.pc docs/Makefile + docs/reference/version.xml gobject/Makefile examples/Makefile tests/Makefile diff --git a/docs/Makefile.am b/docs/Makefile.am index 2295387..f01825a 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,6 +1,7 @@ REF_VERSION = $(PYGOBJECT_MAJOR_VERSION).$(PYGOBJECT_MINOR_VERSION) XMLFILES = \ + reference/pygobject-introduction.xml \ reference/pygobject-classes.xml \ reference/pygobject-constants.xml \ reference/pygobject-ref.xml \ @@ -24,6 +25,8 @@ XSL_DATA = $(XSLFILES) HTMLdir = $(datadir)/gtk-doc/html/pygobject HTML_DATA = \ + html/pygobject-introduction.html \ + html/pygobject-reference-copyright.html \ html/class-gobjectgboxed.html \ html/class-gobjectginterface.html \ html/class-gobjectgpointer.html \ @@ -37,11 +40,14 @@ HTML_DATA = \ html/index.sgml \ html/pygobject.devhelp -BUILT_SOURCES = build_stamp $(HTML_DATA) -CLEANFILES = build_stamp $(HTML_DATA) -EXTRA_DIST = $(XMLFILES) $(XSLFILES) +BUILT_SOURCES = build_stamp $(HTML_DATA) reference/version.xml \ + reference/builddate.xml +CLEANFILES = build_stamp $(HTML_DATA) reference/version.xml \ + reference/builddate.xml +EXTRA_DIST = $(XMLFILES) $(XSLFILES) reference/version.xml.in build_stamp: reference ${XMLFILES} ${XSLFILES} + date '+%B %d, %Y' > reference/builddate.xml xsltproc --nonet --xinclude -o html/ \ --stringparam gtkdoc.bookname "pygobject" \ --stringparam gtkdoc.version ${REF_VERSION} \ 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@ diff --git a/docs/xsl/common.xsl b/docs/xsl/common.xsl index cb4a7d2..606313f 100644 --- a/docs/xsl/common.xsl +++ b/docs/xsl/common.xsl @@ -1,4 +1,4 @@ - + @@ -16,5 +16,4 @@ - diff --git a/docs/xsl/html.xsl b/docs/xsl/html.xsl index 350f183..3bb5638 100644 --- a/docs/xsl/html.xsl +++ b/docs/xsl/html.xsl @@ -1,4 +1,4 @@ - + @@ -262,6 +262,22 @@ + + + + + + + + + + + + + + + + diff --git a/docs/xsl/ref-html-style.xsl b/docs/xsl/ref-html-style.xsl index 124a117..4fc86e7 100644 --- a/docs/xsl/ref-html-style.xsl +++ b/docs/xsl/ref-html-style.xsl @@ -1,4 +1,4 @@ - + @@ -14,7 +14,7 @@ - @@ -23,16 +23,18 @@ - <ANCHOR id=" - - " href=" - - - / - - - "> + + <ANCHOR id=" + + " href=" + + + / + + + "> + -- cgit