Commits

lakka  committed 425f27a

reorganising intro

  • Participants
  • Parent commits 0a92ca6

Comments (0)

Files changed (5)

File pyobjc-core/Doc/index.rst

    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to PyObjC's documentation!
-=======================================
+=========================
+An introduction to PyObjC
+=========================
+
+PyObjC is a bridge between Python and Objective-C.  It allows Python 
+scripts to use and extend existing Objective-C class libraries;
+most importantly the `Cocoa libraries`_ by `Apple`_.
+
+This guide explains how to use Objective-C class libraries from Python
+scripts and how to interpret the documentation of those libraries from the 
+point of view of a Python programmer.
 
 Contents:
 
    :maxdepth: 2
    :glob:
 
-   introduction
    install
-   
+   introduction/introduction
+   introduction/first-steps
+      
    typemapping
    advanced/index
    tutorials/index

File pyobjc-core/Doc/introduction.rst

-=========================
-An introduction to PyObjC
-=========================
-
-PyObjC is a bridge between Python and Objective-C.  It allows Python 
-scripts to use and extend existing Objective-C class libraries;
-most importantly the `Cocoa libraries`_ by `Apple`_.
-
-This guide explains how to use Objective-C class libraries from Python
-scripts and how to interpret the documentation of those libraries from the 
-point of view of a Python programmer.
-
-Before jumping into PyObjC development, you should take some time to
-understand a little bit about Objective-C. The class libraries that
-you will be using from Cocoa are not documented in Python, and their
-documentation will be confusing without a grasp on the semantics and syntax of
-Objective-C.
-
-.. toctree::
-   :maxdepth: 2
-
-   introduction/objective-c
-   introduction/first steps
-   
-
-.. _`Apple`: http://www.apple.com/
-.. _`Cocoa libraries`: http://developer.apple.com/technologies/mac/cocoa.html

File pyobjc-core/Doc/introduction/first steps.rst

 .. highlight:: python
     :linenothreshold: 5
 
-Objective-C is an object-oriented programming language implemented as a
-superset of C that borrows heavily in concept and syntax from Smalltalk. It
-features single inheritance with dynamic dispatch and (in theory) multiple
-root classes. This is basically the same as Python with single inheritance.
 
-Objective-C code looks just like plain C code, with some easily recognizable
-Smalltalk-like extensions for the object-oriented parts of the language. An
-example class declaration (usually found in ``.h`` files) and implementation
-(usually found in ``.m`` files) are listed below. Class declarations are
-easily recognized as blocks of code between ``@interface`` and ``@end``, and
-similarly the implementation is between ``@implementation`` and ``@end``
 
 When dealing with the Objective-C runtime, there are certain patterns
 you need to learn when writing Python code.  If you're not already an

File pyobjc-core/Doc/introduction/introduction.rst

+===========================
+An introduction Objective-C
+===========================
+
+Before jumping into PyObjC development, you should take some time to
+understand a little bit about Objective-C. The class libraries that you will
+be using from Cocoa are not documented in Python, and their documentation will
+be confusing without a grasp on the semantics and syntax of Objective-C.
+
+Objective-C is an object-oriented programming language implemented as a
+superset of C that borrows heavily in concept and syntax from Smalltalk. It
+features single inheritance with dynamic dispatch and (in theory) multiple
+root classes. This is basically the same as Python with single inheritance.
+
+Objective-C code looks just like plain C code, with some easily recognizable
+Smalltalk-like extensions for the object-oriented parts of the language. An
+example class declaration (usually found in ``.h`` files) and implementation
+(usually found in ``.m`` files) are listed below. Class declarations are
+easily recognized as blocks of code between ``@interface`` and ``@end``, and
+similarly the implementation is between ``@implementation`` and ``@end``
+
+A class declaration:
+
+.. sourcecode:: objective-c
+    :linenos:
+
+    @interface MyClass : MySuperClass
+    {
+        id  anInstanceVariable;
+        int anotherInstanceVariable;
+    }
+
+    // A class method that returns an initialized instance of this class.
+    // Similar to an implementation of __call__ on the metaclass.
+    +instanceWithObject:(id)anObject andInteger:(int)anInteger;
+
+    // An instance method, the designated initializer for MyClass.
+    // Similar to an implementation of __new__ on MyClass.
+    -initWithObject:(id)anObject andInteger:(int)anInteger;
+
+    // An accessor, instance variables (attributes) are in a separate
+    // namespace and are considered "private" in Objective-C.  Conventionally,
+    // there is nothing similar to this in Python.
+    -(int)anotherInstanceVariable;
+    @end
+
+A class implementation:
+
+.. sourcecode:: objective-c
+    :linenos:
+
+    @implementation MyClass
+
+    // Note that a type is not declared for the return value.  Undeclared types
+    // are assumed to be "id", which means any kind of instance.
+    +instanceWithObject:(id)anObject andInteger:(int)anInteger
+    {
+        // 1. Create an instance of MyClass.
+        // 2. Initialize it with its designated initializer
+        //    "initWithObject:andInteger:".
+        // 3. Autorelease it, so that it does not leak memory.
+        // 4. Return the new instance.
+        //
+        // NOTE:
+        //   By convention,initializers (such as +new, -init, -copy)
+        //   are the only methods that should return retained objects.
+        //
+        // NOTE:
+        //   Since this is a class method, "self" refers to the class!
+        //
+        // Very roughly similar to:
+        //   return self.__new__(anObject, anInteger)
+        return [[[self alloc] initWithObject:anObject andInteger:anInteger] autorelease];
+    }
+
+    // Note that a type is not declared for the return value.  Undeclared types
+    // are assumed to be "id", which means any kind of instance.
+    -initWithObject:(id)anObject andInteger:(int)anInteger
+    {
+        // Call the designated initializer of the superclass.
+        // Similar to:
+        //     self = super(MyClass, self).__new__()
+        self = [super init];
+
+        // Bail if initialization of the superclass failed.
+        // Similar to:
+        //     if self is None:
+        //         return None
+        if (!self) {
+            return nil;
+        }
+
+        // Set the instance variable (attribute).  The argument must be
+        // retained, since it will persist as long as the instance does.
+        // Similar to:
+        //     # Reference counting is automatic in Python
+        //     self.anInstanceVariable = anObject
+        anInstanceVariable = [anObject retain];
+
+        // Set the other instance variable.  Note that since anInteger is
+        // a primitive "C" type, not an object, no reference counting takes
+        // place.
+        // Similar to:
+        //     # Everything is an object in Python
+        //     self.anotherInstanceVariable = anInteger
+        anotherInstanceVariable = anInteger;
+
+        // Like __new__ in Python, initializers in Objective-C must
+        // explicitly return self.  Note that this is different from
+        // __init__.
+        // Similar to:
+        //     return self
+        return self;
+    }
+        
+
+    // an accessor, instance variables (attributes) are in a separate
+    // namespace and are considered "private"
+    -(int)anotherInstanceVariable
+    {
+        return anotherInstanceVariable;
+    }
+
+    // Since objects were retained as instance variables on this object,
+    // they must be freed when the object is.  This is similar to an
+    // implementation of __del__ in Python.  Since Objective-C has no
+    // cyclic garbage collection, this isn't discouraged like it is in
+    // Python.
+    -(void)dealloc
+    {
+        // Very roughly similar to:
+        //     del self.instanceVariable
+        [instanceVariable release];
+
+        // Very roughly similar to:
+        //     super(MyClass, self).__del__()
+        [super dealloc];
+    }
+
+    @end
+
+This guide cannot teach you Objective-C. If you want more information, see:
+
+    * `The Objective-C Programming Language`_ at `Apple`_.
+
+    .. _`The Objective-C Programming Language`: http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html
+
+   
+
+.. _`Apple`: http://www.apple.com/
+.. _`Cocoa libraries`: http://developer.apple.com/technologies/mac/cocoa.html

File pyobjc-core/Doc/introduction/objective-c.rst

 will be ``nil``.  PyObjC translates ``nil`` to ``None`` when crossing the
 bridge, so any such attempt will raise an ``AttributeError``.
 
-For more information about Objective-C see:
 
-* `The Objective-C Programming Language`_ at `Apple`_.
-
-.. _`The Objective-C Programming Language`: http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html
-
-A class declaration:
-
-.. sourcecode:: objective-c
-    :linenos:
-
-    @interface MyClass : MySuperClass
-    {
-        id  anInstanceVariable;
-        int anotherInstanceVariable;
-    }
-
-    // A class method that returns an initialized instance of this class.
-    // Similar to an implementation of __call__ on the metaclass.
-    +instanceWithObject:(id)anObject andInteger:(int)anInteger;
-
-    // An instance method, the designated initializer for MyClass.
-    // Similar to an implementation of __new__ on MyClass.
-    -initWithObject:(id)anObject andInteger:(int)anInteger;
-
-    // An accessor, instance variables (attributes) are in a separate
-    // namespace and are considered "private" in Objective-C.  Conventionally,
-    // there is nothing similar to this in Python.
-    -(int)anotherInstanceVariable;
-    @end
-
-A class implementation:
-
-.. sourcecode:: objective-c
-    :linenos:
-
-    @implementation MyClass
-
-    // Note that a type is not declared for the return value.  Undeclared types
-    // are assumed to be "id", which means any kind of instance.
-    +instanceWithObject:(id)anObject andInteger:(int)anInteger
-    {
-        // 1. Create an instance of MyClass.
-        // 2. Initialize it with its designated initializer
-        //    "initWithObject:andInteger:".
-        // 3. Autorelease it, so that it does not leak memory.
-        // 4. Return the new instance.
-        //
-        // NOTE:
-        //   By convention,initializers (such as +new, -init, -copy)
-        //   are the only methods that should return retained objects.
-        //
-        // NOTE:
-        //   Since this is a class method, "self" refers to the class!
-        //
-        // Very roughly similar to:
-        //   return self.__new__(anObject, anInteger)
-        return [[[self alloc] initWithObject:anObject andInteger:anInteger] autorelease];
-    }
-
-    // Note that a type is not declared for the return value.  Undeclared types
-    // are assumed to be "id", which means any kind of instance.
-    -initWithObject:(id)anObject andInteger:(int)anInteger
-    {
-        // Call the designated initializer of the superclass.
-        // Similar to:
-        //     self = super(MyClass, self).__new__()
-        self = [super init];
-
-        // Bail if initialization of the superclass failed.
-        // Similar to:
-        //     if self is None:
-        //         return None
-        if (!self) {
-            return nil;
-        }
-
-        // Set the instance variable (attribute).  The argument must be
-        // retained, since it will persist as long as the instance does.
-        // Similar to:
-        //     # Reference counting is automatic in Python
-        //     self.anInstanceVariable = anObject
-        anInstanceVariable = [anObject retain];
-
-        // Set the other instance variable.  Note that since anInteger is
-        // a primitive "C" type, not an object, no reference counting takes
-        // place.
-        // Similar to:
-        //     # Everything is an object in Python
-        //     self.anotherInstanceVariable = anInteger
-        anotherInstanceVariable = anInteger;
-
-        // Like __new__ in Python, initializers in Objective-C must
-        // explicitly return self.  Note that this is different from
-        // __init__.
-        // Similar to:
-        //     return self
-        return self;
-    }
-        
-
-    // an accessor, instance variables (attributes) are in a separate
-    // namespace and are considered "private"
-    -(int)anotherInstanceVariable
-    {
-        return anotherInstanceVariable;
-    }
-
-    // Since objects were retained as instance variables on this object,
-    // they must be freed when the object is.  This is similar to an
-    // implementation of __del__ in Python.  Since Objective-C has no
-    // cyclic garbage collection, this isn't discouraged like it is in
-    // Python.
-    -(void)dealloc
-    {
-        // Very roughly similar to:
-        //     del self.instanceVariable
-        [instanceVariable release];
-
-        // Very roughly similar to:
-        //     super(MyClass, self).__del__()
-        [super dealloc];
-    }
-
-    @end
-
-