php-gtk:gtkphd

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
ideas:gtkphd [2009/05/02 16:29] – moved from gsoc 2009, added progress/status philipphp-gtk:gtkphd [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
-==== PHP-GTK PhD migration ==== +==== Migration to Main Manual ==== 
-PHP-GTK's docs should be moved to the [[doc:phd|PhD]] rendering system, but it is a fairly large job.+The PHP-GTK manual will be integrated into the main PHP manual as an extension.
  
-Would involve +=== Progress ===
-  - migrating the current documentation to a docbook 5 format +
-  - writing a PhD compatible theme to generate documentation +
-  - writing a reflection based updater to keep docs up to date with code (parsing signals, methods, properties and updating the xml) +
-  - getting autogeneration set up so PHP-GTK docs are generated on a regular basis+
  
-==== Progress ==== +== Stage One == 
-Some work has been done+  - <del>Create branches to phpdoc/doc-base and phpdoc/en</del> 
 +  - <del>Patch docgen.php script for PHP-GTK-specific Reflection idiosyncrasies.</del> 
 +  - Create new docgen template set for PHP-GTK. __In Progress__ 
 +    * gtk/book.tpl 
 +    * gtk/chapter.tpl (GTK+ sub-extensions) 
 +    * gtk/class.tpl 
 +      * <del>fields (aka GObject properties)</del> 
 +      * signals 
 +    * gtk/configure.tpl 
 +    * gtk/constants.tpl 
 +    * gtk/method.tpl 
 +    * gtk/part.tpl (sub-extension parts) 
 +    * gtk/reference.tpl 
 +    * gtk/signal.tpl 
 +  - Finalize book format
  
-==== Status ==== +== Stage Two == 
-Unknown+  - Copy as much well-formed documentation as possible from the [[http://gtk.php.net/manual/en/|old manual]], without muddying the new format. 
 +  - Fill in any glaringly-missing documentation 
 +  - Merge branch into phpdoc/en/trunk/ 
 + 
 +=== Branches === 
 +[[http://svn.php.net/viewvc/phpdoc/doc-base/branches/gtk-docgen/|phpdoc/doc-base/branches/gtk-docgen/]]: A fork of the docgen scripts to accommodate PHP-GTK's Reflection idiosyncrasies. 
 + 
 +[[http://svn.php.net/viewvc/phpdoc/en/branches/php-gtk/|phpdoc/en/branches/php-gtk/]]: Branching the main manual so that our work on the PHP-GTK book doesn't interfere with "normal operations." 
 + 
 +[[http://svn.php.net/viewvc/phpdoc/modules/doc-gtk/|phpdoc/modules/doc-gtk/]]: Module for checking out PHP-GTK externals into a single working copy. 
 + 
 +=== Reflection Idiosyncrasies === 
 +PHP-GTK does not currently have proper Reflection data, beyond regular class->method, and such, linking. This means that the docgen.php script, which relies heavily on Reflection information, does not function properly without modification. 
 + 
 +The current solution to this issue is to utilize the .defs files present in the PHP-GTK extension sources, which themselves establish which classes exist in the extension. This is done by simply reading in all of the .defs files, then regex'ing them for of-object specifications, then running array_unique on the resulting set of class names. This produces a list of all defined classes in PHP-GTK. 
 + 
 +=== PHP-GTK-specific Constructs === 
 +PHP-GTK utilizes some constructs that are not present in other extensions; or, at least, are not standard. These need to be marked up specially for PHP-GTK. 
 + 
 +== Fields == 
 +Each widget class in PHP-GTK has a set of associated properties which are separate from both its member properties and inherited properties. These "GObject properties" are enumerated using GObject::list_properties(int gtype), where gtype is ClassName::gtype. 
 + 
 +== Signals == 
 +Each widget class in PHP-GTK has a set of signals, which are essentially callback names for certain actions. One example is the GtkButton "clicked" signal, which is emitted when a user clicks on that GtkButton widget. 
 + 
 +These signals can simply be marked up as a variant of the method format, as they are primarily callbacks. There are a [[http://gtk.php.net/manual/en/gobject.method.signal_query.php|few bits of information]] that are important to be clearly documented for each signal: 
 +  * ID 
 +     Each signal has a signal ID associated with it. 
 +  * Name 
 +     Each signal has a name. 
 +  * Emitting Classes 
 +     The list of classes which emit that signal 
 +  * [[http://gtk.php.net/manual/en/gobject.enum.gsignalflags.php|GSignalFlags]] 
 +     The signal flags are used to specify a signal's behaviour, the overall signal description outlines how the stages of a signal emission occur. 
 +  * Return Type 
 +  * Parameters 
 +     Each signal handler callback accepts certain parameters, which are passed in when called. This is usually at the very least the object which emitted the signal. 
 + 
 +=== Book Structure === 
 +  * PHP-GTK (Book) 
 +    * GTK+ (Part) 
 +      * ATK (Chapter) 
 +      * GDK (Chapter) 
 +      * GTK (Chapter) 
 +      * Pango (Chapter) 
 +    * Extra (Part) 
 +    * [...] (Part)
php-gtk/gtkphd.1241281787.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools