Improving the docs

README.md

@@ -1,206 +1,28 @@
 Pheasant
-=======================================
+========
 
 Pheasant is an object relational mapper written to take advantage of PHP 5.3. Simple relationships
 are supported, with the emphasis being on scalability and performance over complexity.
 
 Pheasant doesn't attempt to abstract the database and makes heavy use of
 MySQL/Innodb features.
 
-More details available at http://getpheasant.com
+The docs are located at: https://pheasant.readthedocs.org/en/latest/index.html
+
 
 Status of Development
----------------------------------
+---------------------
 
 Running in production on 99designs.com. See `ROADMAP` for more details on future plans.
 
 [![Build Status](https://travis-ci.org/lox/pheasant.png)](https://travis-ci.org/lox/pheasant)
 
+
 Installing
----------------------------------
+----------
 
 Easiest way is to install via composer http://packagist.org/packages/lox/pheasant.
 
-Persisting Objects
----------------------------------
-
-Each domain object has a set of properties and relationships that are defined in the
-configure method. Each domain object delegates to a mapper object for the actual saving
-and loading of objects.
-
-```php
-<?php
-
-use \Pheasant;
-use \Pheasant\Types;
-
-class Post extends DomainObject
-{
-  public function properties()
-  {
-    return array(
-      'postid'   => new Types\Sequence(),
-      'title'    => new Types\String(255, 'required'),
-      'subtitle' => new Types\String(255),
-      'status'   => new Types\Enum(array('closed','open')),
-      'authorid' => new Types\Integer(11),
-      );
-  }
-
-  public function relationships()
-  {
-    return array(
-      'Author' => Author::hasOne('authorid')
-    );
-  }
-}
-
-class Author extends DomainObject
-{
-  public function properties()
-  {
-    return array(
-      'authorid' => new Types\Sequence(),
-      'fullname' => new Types\String(255, 'required')
-    );
-  }
-
-  public function relationships()
-  {
-    return array(
-      'Posts' => Post::hasOne('authorid')
-    );
-  }
-}
-
-// configure database connection
-Pheasant::setup('mysql://localhost:/mydatabase');
-
-// create some objects
-$author = new Author(array('fullname'=>'Lachlan'));
-$post = new Post(array('title'=>'My Post', 'author'=>$author));
-
-// save objects
-$author->save();
-$post->save();
-
-echo $post->title; // returns 'My Post'
-echo $post->Author->fullname; // returns 'Lachlan'
-```
-
-Magical Finders
----------------------------------
-
-Many variations of finders are available for locating objects:
-
-```php
-<?php
-
-// all users
-$users = User::all();
-
-// all users named frank
-$users = User::find('firstname = ?', 'frank');
-
-// any fields can be used in finders, this translates to above
-$users = User::findByFirstName('frank');
-
-// a single user named frank
-$users = User::one('firstname = ?', 'frank');
-
-// a user by primary key
-$user = User::byId(1);
-
-```
-
-Collection Scoping
-------------------------------------
-Scoping allows you to specify commonly-used queries which can be referenced as method calls on Collection objects. All scope methods will return a Pheasant::Collection object which will allow for further methods (such as other scopes) to be called on it.
-
-To define a simple scope, we first define a `scopes` method in our `DomainObject` that returns an associative array in `"methodName" => $closure` form.
-
-```php
-use \Pheasant;
-Class User extends DomainObject
-{
-  public function scopes()
-  {
-    return array(
-      'active' => function($collection){
-        $collection->filter('last_login_date >= ?', strtotime('30 days ago'));
-      },
-    );
-  }
-}
-
-// Scopes may be used by invoking them like methods
-User::all()->active()
-//=> Returns all active users
-```
-
-Events
----------------------------------
-
-Code can be triggered before and after create, update and delete operations.
-
-```php
-<?php
-
-use \Pheasant;
-use \Pheasant\Events;
-use \Pheasant\Types;
-
-class Post extends DomainObject
-{
-  public function properties()
-  {
-    return array(
-      'postid'      => new Types\Sequence(),
-      'title'       => new Types\String(255),
-      'timecreated' => new Types\Integer(11),
-      ));
-  }
-
-  public function beforeCreate($post)
-  {
-    $d->timecreated = time();
-  }
-}
-```
-
-Optionally, domain objects provide the following implicit hooks which can be overriden:
-
-- afterCreate
-- beforeUpdate, afterUpdate
-
-Transactions
-------------------------------------
-
-Transactions can be created globally:
-
-```php
-<?php
-
-
-\Pheasant::transaction(function() {
-  $post = new Post(array('title'=>'First Post!'));
-  $post->save();
-});
-
-```
-
-Or transactions can be invoked on an instance:
-
-```php
-<?php
-
-$post = new Post(array('title'=>'First Post!'));
-
-$post->transaction(function($obj) {
-  $obj->save();
-});
-
-```
 
 Contributors
 ------------

docs/conf.py

@@ -41,16 +41,16 @@
 
 # General information about the project.
 project = u'Pheasant'
-copyright = u'2013, Lachlan Donald'
+copyright = u'2013-2015, Lachlan Donald'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.1.0'
+version = '1.4.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.1.0'
+release = '1.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/domainobjects.rst

@@ -3,6 +3,42 @@ Domain Objects
 
 The domain object represents an object that can be persisted in Pheasant.
 
+
+Basic example
+-------------
+
+.. code-block:: php
+
+    <?php
+
+    use \Pheasant;
+    use \Pheasant\Types;
+
+    class Post extends DomainObject
+    {
+        public function properties()
+        {
+            return array(
+                'postid'    => new Types\Integer(11, 'primary auto_increment'),
+                'title'     => new Types\String(255, 'required'),
+                'type'      => new Types\String(128, 'default=blog'),
+                'timestamp' => new Types\DateTime(),
+                'authorid'  => new Types\Integer(11)
+            );
+        }
+    }
+
+
+Defining properties
+-------------------
+
+Each DomainObject should at least define a `properties()` method. In the `properties()` you set
+which columns you have in your database table, and what type they are. There are built-in types
+for the most used MySQL column types.
+
+See doc:`types` for more details.
+
+
 Initialization
 --------------
 
@@ -21,10 +57,10 @@ The initialization happens in `DomainObject::initialize`, for which the default
 look for several template methods in the object.
 
 properties()
-    A map of column names to Type objects (see `mapping/types`)
+    A map of column names to Type objects (see `types`)
 
 relationships()
-    A map of keys to RelationType objects representing 1-n or 1-1 relationships  (see `mapping/relationships`)
+    A map of keys to RelationType objects representing 1-n or 1-1 relationships  (see `relationships`)
 
 tableName()
     The database table name to map to, defaults to the name of the class
@@ -105,10 +141,65 @@ Inheritance and extending domain objects isn't something that has any explicit s
 be possible to override the `properties` method and extend it.
 
 
+Defining events
+---------------
 
+Code can be triggered before and after create, update and delete operations.
 
+.. code-block:: php
 
+    <?php
 
+    use \Pheasant;
+    use \Pheasant\Events;
+    use \Pheasant\Types;
 
+    class Post extends DomainObject
+    {
+      public function properties()
+      {
+        return array(
+          'postid'      => new Types\Sequence(),
+          'title'       => new Types\String(255),
+          'timecreated' => new Types\Integer(11),
+          ));
+      }
+
+      public function beforeCreate($post)
+      {
+        $d->timecreated = time();
+      }
+    }
+
+Optionally, domain objects provide the following implicit hooks which can be overriden:
+
+- `afterCreate`
+- `beforeUpdate`, `afterUpdate`
+
+
+Transactions
+------------
+
+Transactions can be created globally:
+
+.. code-block:: php
+
+    <?php
+
+
+    \Pheasant::transaction(function() {
+      $post = new Post(array('title'=>'First Post!'));
+      $post->save();
+    });
+
+Or transactions can be invoked on an instance:
+
+.. code-block:: php
+
+    <?php
 
+    $post = new Post(array('title'=>'First Post!'));
 
+    $post->transaction(function($obj) {
+      $obj->save();
+    });