docs update

CHANGELOG.rst

@@ -8,9 +8,11 @@ Changelog
 - Added: `SQLObject <http://www.sqlobject.org>`__ ORM support
 - Added: PostgreSQL: New ``integer`` (thanks to `Nikolay Yarovoy <https://github.com/nickspring>`__),
   ``string_firstchars`` (thanks to `Dmitry Brytkov <https://github.com/dimoha>`__) and ``string_lastchars``
-  range partition subtypes
+  range partition subtypes, see `docs <http://architect.readthedocs.org/features/partition/postgresql.html
+  #range>`__ for details
 - Changed: ``range`` partition option renamed to ``constraint`` to better suit new partition subtypes
-- Changed: PostgreSQL: Triggers refactoring and speedups
+- Changed: PostgreSQL: Triggers refactoring and speedups, don't forget to rerun ``partition`` command to
+  apply new refactored triggers to the database
 - Fixed: ``architect.uninstall`` decorator wasn't able to restore modified model methods under
   Python 3
 

README.rst

@@ -21,16 +21,16 @@ Features
 
 * Supported ORMs
 
-  - Django
-  - Peewee
-  - Pony
-  - SQLAlchemy
-  - SQLObject
+  - `Django <https://www.djangoproject.com>`_ >= 1.4
+  - `Peewee <https://peewee.readthedocs.org>`_ >= 2.2.0
+  - `Pony <http://ponyorm.com>`_ >= 0.5.0
+  - `SQLAlchemy <http://www.sqlalchemy.org>`_ >= 0.8.0
+  - `SQLObject <http://www.sqlobject.org>`_ >= 1.5.0
 
 * Supported DBs
 
-  - PostgreSQL
-  - MySQL
+  - `PostgreSQL <http://www.postgresql.org>`_ >= 8.0
+  - `MySQL <https://www.mysql.com>`_ >= 5.5
 
 * Supports Python 2.6 - 3.4
 * Extensively documented

architect/orms/bases.py

@@ -79,7 +79,7 @@ class BasePartitionFeature(BaseFeature):
 
     def get_partition(self):
         """
-        Returns requested partition type object to work with.
+        Returns partition type object to work with depending on the given partition options.
         """
         database = get_database_module(self.model_meta['dialect'])
 
@@ -100,7 +100,7 @@ def get_partition(self):
     @property
     def model_meta(self):
         """
-        Returns dictionary of model meta attributes under common names.
+        Returns dictionary of model meta attributes needed for partitioning under common names.
         """
         raise NotImplementedError('Property "model_meta" not implemented in: {0}'.format(self.__class__.__name__))
 

docs/conf.py

@@ -80,17 +80,25 @@
 htmlhelp_basename = 'Architectdoc'
 
 
-# Returns method name without class name or module name prepended
-class MethodNameDocumenter(sphinx.ext.autodoc.MethodDocumenter):
-    objtype = 'methodname'
-
+# Returns object name without class name or module name prepended
+class NameOnlyMixin(object):
     def format_name(self):
         name = self.objpath[1]
         self.objpath = None
         return name
 
 
+class AttributeNameOnlyDocumenter(NameOnlyMixin, sphinx.ext.autodoc.AttributeDocumenter):
+    objtype = 'attribute-name-only'
+    directivetype = 'attribute'
+
+
+class MethodNameOnlyDocumenter(NameOnlyMixin, sphinx.ext.autodoc.MethodDocumenter):
+    objtype = 'method-name-only'
+
+
 # Documentation setup
 def setup(app):
     app.add_stylesheet('css/architect.css')
-    app.add_autodocumenter(MethodNameDocumenter)
+    app.add_autodocumenter(AttributeNameOnlyDocumenter)
+    app.add_autodocumenter(MethodNameOnlyDocumenter)

docs/features/index.rst

@@ -11,10 +11,10 @@ all of its features despite of the ORM being used.
 
 .. raw:: html
 
-    <h2 id="install">
-        install
-        <a class="headerlink" href="#install" title="Permalink to this headline">¶</a>
-    </h2>
+   <h2 id="install">
+       install
+       <a class="headerlink" href="#install" title="Permalink to this headline">¶</a>
+   </h2>
 
 All features in Architect are installed into models using ``install`` decorator. An ``install``
 decorator in it's general form can be written as the following:
@@ -59,10 +59,10 @@ This provides 100% non-conflicting behaviour with all ORMs and other 3rd party p
 
 .. raw:: html
 
-    <h2 id="uninstall">
-        uninstall
-        <a class="headerlink" href="#uninstall" title="Permalink to this headline">¶</a>
-    </h2>
+   <h2 id="uninstall">
+       uninstall
+       <a class="headerlink" href="#uninstall" title="Permalink to this headline">¶</a>
+   </h2>
 
 Under some circumstances a model might not need one or all of the installed features anymore, one
 example can be a model inheritance, where the parent model has a feature installed and a child model
@@ -79,8 +79,8 @@ doesn't want to use it. A feature can be easily uninstalled from a model using `
 where a ``feature`` is a feature name as a string which was installed before.
 
 .. toctree::
-    :hidden:
-    :maxdepth: 1
+   :hidden:
+   :maxdepth: 1
 
-    operation
-    partition
+   operation
+   partition/index

docs/features/operation.rst

@@ -3,18 +3,9 @@ Operations
 
 Sometimes there is a need to execute raw SQL statements, unfortunately different ORMs provide
 different APIs to work with raw SQL. This feature creates an abstraction layer to execute raw
-SQL statements which will work with any supported ORM. Operation feature is supported by Architect
-for the following ORMs:
-
-* `Django <https://www.djangoproject.com>`_ >= 1.4
-* `Peewee <https://peewee.readthedocs.org>`_ >= 2.2.0
-* `Pony <http://ponyorm.com>`_ >= 0.5.0
-* `SQLAlchemy <http://www.sqlalchemy.org>`_ >= 0.8.0
-* `SQLObject <http://www.sqlobject.org>`_ >= 1.5.0
-
-This feature is used by all other Architect features internally and usually doesn't need to be
-installed separately. If this is the only feature that will be used in the model it should be
-installed like this:
+SQL statements which will work with any supported ORM. It is used by all other Architect
+features internally and usually doesn't need to be installed separately. However, if this is
+the only feature that will be used in the model it can be installed like this:
 
 .. code-block:: python
 
@@ -24,9 +15,16 @@ installed like this:
    class Model(object):
        pass
 
-After the installation it can be accessed via ``Model.architect.operation``. Operation feature
+.. raw:: html
+
+   <h2 id="api">
+       API
+       <a class="headerlink" href="#api" title="Permalink to this headline">¶</a>
+   </h2>
+
+After the installation operation feature can be accessed via ``Model.architect.operation``. It
 provides the following methods:
 
-.. automethodname:: architect.orms.bases.BaseOperationFeature.execute
-.. automethodname:: architect.orms.bases.BaseOperationFeature.select_one
-.. automethodname:: architect.orms.bases.BaseOperationFeature.select_all
+.. automethod-name-only:: architect.orms.bases.BaseOperationFeature.execute
+.. automethod-name-only:: architect.orms.bases.BaseOperationFeature.select_one
+.. automethod-name-only:: architect.orms.bases.BaseOperationFeature.select_all

docs/features/partition/index.rst

@@ -0,0 +1,77 @@
+Table partitioning
+==================
+
+Table partitioning is a division of one table into several tables, called partitions, which still
+represent original table. This is usually done for manageability, performance or availability reasons.
+If you are unsure whether you need partitioning or not, then you almost certainly don't need it.
+
+To use this feature, define the model as usual and create a table for it in the database using the
+usual tools that your ORM provides. After the table was created, this feature can be installed into
+the model as the following:
+
+.. code-block:: python
+
+   import architect
+
+   @architect.install('partition', **options)
+   class Model(object):
+       pass
+
+where ``options`` are:
+
+- ``type`` (required). Partition type, e.g. ``range``, ``list`` etc
+- ``subtype`` (required). Partition subtype, e.g. ``date``, ``integer`` etc
+- ``constraint`` (required). What data fits into partition, e.g. ``day``, ``5`` (every 5 items) etc
+- ``column`` (required). Column, which value determines which partition record belongs to
+- ``dsn`` (optional). Data Source Name in the form of dialect://user:pass@host/database. Currently needed
+  only for SQLAlchemy ORM.
+
+Above options can take different values depending on the database type because different databases support
+different partition types, subtypes etc. To find out which values can be set for the above options choose
+the database type which you currently use from the list below:
+
+.. toctree::
+   :maxdepth: 1
+
+   postgresql
+   mysql
+
+.. note::
+
+   Using this feature with a Django ORM, run the following command before moving to next step,
+   substituting ``mysite.settings`` to the real path of the Django settings module:
+
+   .. code-block:: bash
+
+      $ export DJANGO_SETTINGS_MODULE=mysite.settings
+
+After the feature has been installed into the model, run the following console command:
+
+.. code-block:: bash
+
+   $ architect partition --module path.to.the.model.module
+
+That's it. Now, when a new record will be inserted, a value from column, specified in the ``column``
+option will be used to determine into what partition the data should be saved. Keep in mind that if
+new partitioned models are added or any settings are changed in existing partitioned models, the
+partition command should be rerun, otherwise the database won't know about this changes.
+
+.. raw:: html
+
+   <h2 id="api">
+       API
+       <a class="headerlink" href="#api" title="Permalink to this headline">¶</a>
+   </h2>
+
+After the installation partition feature can be accessed via ``Model.architect.partition``, though it
+usually doesn't need to be accessed directly because everything is done automatically. It provides the
+following methods:
+
+.. autoattribute-name-only:: architect.orms.bases.BasePartitionFeature.model_meta
+.. automethod-name-only:: architect.orms.bases.BasePartitionFeature.get_partition
+
+   This object provides the following methods:
+
+   .. automethod-name-only:: architect.databases.bases.BasePartition.prepare
+   .. automethod-name-only:: architect.databases.bases.BasePartition.create
+   .. automethod-name-only:: architect.databases.bases.BasePartition.exists