Commits

Ronald Oussoren committed 6a02217

More documentation updates. The end-user documentation should be fairly
complete by now.

Comments (0)

Files changed (4)

pyobjc/Doc/PyObjCTools.html

 <ul>
 <li><code><span>PyObjCTools.KeyValueCoding.py</span></code></li>
 </ul>
-<p>A python API for working with Key-Value Coding. XXX: Link</p>
+<p>A python API for working with <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i">Key-Value Coding</a>.</p>
 <ul>
 <li><code><span>PyObjCTools.NibClassBuilder.py</span></code></li>
 </ul>
 </li>
 </ul>
 <h2><a name="pyobjctools-nibclassbuilder">PyObjCTools.NibClassBuilder</a></h2>
-<p>XXX: Read the online documetation</p>
+<h3><a name="extracting-class-definitions-from-nibs">Extracting class definitions from nibs</a></h3>
+<p>The module maintains a global set of class definitions, extracted from
+nibs. To add the classes from a nib to this set, use the <code><span>extractClasses()</span></code>
+function. It can be called in two ways:</p>
+<ul>
+<li><code><span>extractClasses(nibName,</span> <span>bundle=&lt;main-bundle&gt;)</span></code><p>This finds the nib by name from a bundle. If no bundle
+if given, the main bundle is searched.</p>
+</li>
+<li><code><span>extractClasses(path=pathToNib)</span></code><p>This uses an explicit path to a nib.</p>
+</li>
+</ul>
+<p><code><span>extractClasses()</span></code> can be called multiple times for the same bundle: the
+results are cached so no almost extra overhead is caused.</p>
+<h3><a name="using-the-class-definitions">Using the class definitions</a></h3>
+<p>The module contains a &quot;magic&quot; base (super) class called <code><span>AutoBaseClass</span></code>.
+Subclassing <code><span>AutoBaseClass</span></code> will invoke some magic that will look up the
+proper base class in the class definitions extraced from the nib(s).
+If you use multiple inheritance to use Cocoa's &quot;informal protocols&quot;,
+you <i>must</i> list <code><span>AutoBaseClass</span></code> as the first base class. For example:</p>
+<pre>
+class PyModel(AutoBaseClass, NSTableSource):
+    ...
+</pre>
+<h3><a name="the-nibinfo-class">The <code><span>NibInfo</span></code> class</a></h3>
+<p>The parsing of nibs and collecting the class definition is done by the
+<code><span>NibInfo</span></code> class. You normally don't use it directly, but it's here if you
+have special needs.</p>
+<h3><a name="the-command-line-tool">The command line tool</a></h3>
+<p>When run from the command line, this module invokes a simple command
+line program, which you feed paths to nibs. This will print a Python
+template for all classes defined in the nib(s). For more doco, see
+the commandline_doc variable, or simply run the program wothout
+arguments. It also contains a simple test program.</p>
 <h2><a name="pyobjctools-signals">PyObjCTools.Signals</a></h2>
-<p>XXX: Read the online documetation</p>
+<p>This module provides two functions that can be usefull while investigating
+random crashes of a PyObjC program. These crashes are often caused by 
+Objective-C style weak references or incorrectly implemented protocols.</p>
+<ul>
+<li><code><span>dumpStackOnFatalSignal()</span></code><p>This function will install signal handlers that print a stacktrace and
+then reraise the signal.</p>
+</li>
+<li><code><span>resetFatalSignals()</span></code><p>Restores the signal handlers to the state they had before the call to
+dumpStackOnFatalSignal.</p>
+</li>
+</ul>
+<p>This module is not designed to provide fine grained control over signal 
+handling. Nor is it intended to be terribly robust. It may give usefull
+information when your program gets unexpected signals, but it might just
+as easily cause a crash when such a signal gets in.</p>
 <h2><a name="pyobjctools-pluginbuilder">PyObjCTools.pluginbuilder</a></h2>
-<p>XXX: Read the online documetation</p>
+<p>This module defines one class to build python based plugin bundles for MacOS X.
+Examples of plugin bundles include PreferencePanes and InterfaceBuilder 
+palletes.</p>
+<p>The PluginBuilder class is instantated with a number of keyword arguments and
+have a <code><span>build()</span></code> method that will do all the work.</p>
+<p>XXX: Add documentation about the constructor arguments</p>
+<p>The module contains a main program that can be used in two ways:</p>
+<pre>
+% python pluginbuilder.py [options] build
+
+% python buildplugin.py [options] build
+</pre>
+<p>Where &quot;buildplugin.py&quot; is a user-supplied setup.py-like script following this
+model:</p>
+<pre>
+from PyObjCTools.pluginbuilder import buildplugin
+
+buildplugin(&lt;lots-of-keyword-args&gt;)
+</pre>
+<p>The script will tell you about the supported arguments if you run it without 
+any arguments.</p>
 </body>
 </html>

pyobjc/Doc/PyObjCTools.txt

 
 * ``PyObjCTools.KeyValueCoding.py``
 
-A python API for working with Key-Value Coding. XXX: Link
+A python API for working with `Key-Value Coding`__. 
+
+.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i
 
 * ``PyObjCTools.NibClassBuilder.py``
 
 PyObjCTools.NibClassBuilder
 ...........................
 
-XXX: Read the online documetation
+Extracting class definitions from nibs
+++++++++++++++++++++++++++++++++++++++
+
+The module maintains a global set of class definitions, extracted from
+nibs. To add the classes from a nib to this set, use the ``extractClasses()``
+function. It can be called in two ways:
+
+- ``extractClasses(nibName, bundle=<main-bundle>)``
+
+  This finds the nib by name from a bundle. If no bundle
+  if given, the main bundle is searched.
+
+- ``extractClasses(path=pathToNib)``
+
+  This uses an explicit path to a nib.
+
+``extractClasses()`` can be called multiple times for the same bundle: the
+results are cached so no almost extra overhead is caused.
+
+Using the class definitions
++++++++++++++++++++++++++++
+
+The module contains a "magic" base (super) class called ``AutoBaseClass``.
+Subclassing ``AutoBaseClass`` will invoke some magic that will look up the
+proper base class in the class definitions extraced from the nib(s).
+If you use multiple inheritance to use Cocoa's "informal protocols",
+you *must* list ``AutoBaseClass`` as the first base class. For example::
+
+    class PyModel(AutoBaseClass, NSTableSource):
+        ...
+
+
+The ``NibInfo`` class
++++++++++++++++++++++
+
+The parsing of nibs and collecting the class definition is done by the
+``NibInfo`` class. You normally don't use it directly, but it's here if you
+have special needs.
+
+The command line tool
++++++++++++++++++++++
+
+When run from the command line, this module invokes a simple command
+line program, which you feed paths to nibs. This will print a Python
+template for all classes defined in the nib(s). For more doco, see
+the commandline_doc variable, or simply run the program wothout
+arguments. It also contains a simple test program.
 
 PyObjCTools.Signals
 ...................
 
-XXX: Read the online documetation
+This module provides two functions that can be usefull while investigating
+random crashes of a PyObjC program. These crashes are often caused by 
+Objective-C style weak references or incorrectly implemented protocols.
+
+- ``dumpStackOnFatalSignal()``
+
+  This function will install signal handlers that print a stacktrace and
+  then reraise the signal.
+
+- ``resetFatalSignals()``
+
+  Restores the signal handlers to the state they had before the call to
+  dumpStackOnFatalSignal.
+
+This module is not designed to provide fine grained control over signal 
+handling. Nor is it intended to be terribly robust. It may give usefull
+information when your program gets unexpected signals, but it might just
+as easily cause a crash when such a signal gets in. 
+
 
 PyObjCTools.pluginbuilder
 .........................
 
-XXX: Read the online documetation
+This module defines one class to build python based plugin bundles for MacOS X.
+Examples of plugin bundles include PreferencePanes and InterfaceBuilder 
+palletes.
+
+The PluginBuilder class is instantated with a number of keyword arguments and
+have a ``build()`` method that will do all the work. 
+
+XXX: Add documentation about the constructor arguments
+
+The module contains a main program that can be used in two ways::
+
+  % python pluginbuilder.py [options] build
+
+  % python buildplugin.py [options] build
+
+Where "buildplugin.py" is a user-supplied setup.py-like script following this
+model::
+
+  from PyObjCTools.pluginbuilder import buildplugin
+
+  buildplugin(<lots-of-keyword-args>)
+
+The script will tell you about the supported arguments if you run it without 
+any arguments.

pyobjc/Doc/intro.html

 </ul>
 </li>
 <li><a href="#cocoa-for-python-programmers" id="id10" name="id10">Cocoa for Python programmers</a></li>
-<li><a href="#special-tasks" id="id11" name="id11">Special tasks</a><ul>
+<li><a href="#notes-on-specific-tasks" id="id11" name="id11">Notes on specific tasks</a><ul>
 <li><a href="#working-with-threads" id="id12" name="id12">Working with threads</a></li>
 </ul>
 </li>
 <li><a href="http://www.stepwise.com/">stepwise.com</a></li>
 <li>Your local bookstore or library</li>
 </ul>
-<h2><a href="#id11" name="special-tasks">Special tasks</a></h2>
-<p>XXX: Rename this section</p>
+<h2><a href="#id11" name="notes-on-specific-tasks">Notes on specific tasks</a></h2>
 <h3><a href="#id12" name="working-with-threads">Working with threads</a></h3>
 <p>When you create a thread and want to use PyObjC from that thread you will
 have to create an <code><span>NSAutoreleasePool</span></code> in that thread and clean it up when
 copy the PyObjC modules into the application bundle. This means that this 
 application bundle should be useable on any MacOS X 10.2 system.</p>
 <p>See <a href="ProjectBuilder-Templates.html">the documentation for the templates</a> for more details.</p>
-<p>XXX: But what about Panther, which seems to ship with Python 2.3, at the 
-very least you'll get warnings about the PyObjC extension modules (wrong 
-ABI version).</p>
-<p>XXX: The documentation for the templates should be installed into the 
-documentation folder on the DMG, otherwise the link above won't work, I've
-hacked <code><span>Scripts/update_html.py</span></code> to copy the HTML file to the Doc directory,
-but that is not a pretty solution.</p>
+<p>MacOS X 10.3 seems to ship with Python 2.3 as /usr/bin/python. This means that
+standalone applications build using the Project Builder templates will start
+to complain about Python ABI versions in the <code><span>Console</span></code> when you run them
+on MacOS X 10.3. These are harmless messages caused by the extension modules
+in PyObjC.</p>
 </body>
 </html>

pyobjc/Doc/intro.txt

 
 .. _`stepwise.com`: http://www.stepwise.com/
 
-Special tasks
--------------
-
-XXX: Rename this section
+Notes on specific tasks
+-----------------------
 
 Working with threads
 ....................
 
 .. __: ProjectBuilder-Templates.html
 
-XXX: But what about Panther, which seems to ship with Python 2.3, at the 
-very least you'll get warnings about the PyObjC extension modules (wrong 
-ABI version).
-
-XXX: The documentation for the templates should be installed into the 
-documentation folder on the DMG, otherwise the link above won't work, I've
-hacked ``Scripts/update_html.py`` to copy the HTML file to the Doc directory,
-but that is not a pretty solution.
+MacOS X 10.3 seems to ship with Python 2.3 as /usr/bin/python. This means that
+standalone applications build using the Project Builder templates will start
+to complain about Python ABI versions in the ``Console`` when you run them
+on MacOS X 10.3. These are harmless messages caused by the extension modules
+in PyObjC.