added docs to ranks and vector field

Author: dvdmgl

docs/index.rst

@@ -27,11 +27,13 @@ Features:
 Contents:
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    install
    tutorial
    migrations
+   ranks
+   tsvector_field
    pg_fts
 
 

docs/migrations.rst

@@ -4,34 +4,47 @@ Migrations
 
 .. important::
 
-    If you're not familiar with django Migrations, please check `Migrations Documentation <https://docs.djangoproject.com/en/1.7/topics/migrations/>`_ 1st.
+    If you're not familiar with django Migrations, please check `django Migrations Documentation <https://docs.djangoproject.com/en/1.7/topics/migrations/>`_ 1st.
 
 
 .. important::
 
     The order of Migrations.operations matters, you can only apply a index to a field if a field exists, if you delete a model/field you should remove any operation first before removing model/field.
 
 
-Creating
---------
-
-Trigger
-*******
+BaseVectorOperation options
+***************************
 
-For creating of trigger is provided :class:`~pg_fts.migrations.CreateFTSTriggerOperation`.
+The following arguments are available to all FTSMigration types
 
 ``name``
+--------
 
 .. attribute:: CreateFTSTriggerOperation.name
 
 Name of the model
 
 ``fts_vector``
+--------------
 
 .. attribute:: CreateFTSTriggerOperation.fts_vector
 
 Name of the :class:`~pg_fts.fields.TSVectorField`
 
+
+Creating
+--------
+
+Trigger
+*******
+
+For creating of trigger is provided :class:`~pg_fts.migrations.CreateFTSTriggerOperation`.
+
+``CreateFTSTriggerOperation``
+-----------------------------
+
+.. class:: CreateFTSTriggerOperation(options**)
+
 How it works
 ++++++++++++
 
@@ -91,20 +104,9 @@ Index
 
 For creating of indexes is provided :class:`~pg_fts.migrations.CreateFTSIndexOperation`.
 
-``name``
-
-.. attribute:: CreateFTSIndexOperation.name
-
-Name of the model
-
-``fts_vector``
-
-.. attribute:: CreateFTSIndexOperation.fts_vector
-
-Name of the :class:`~pg_fts.fields.TSVectorField`
-
 
 ``index``
+---------
 
 .. attribute:: CreateFTSIndexOperation.index
 
@@ -116,24 +118,26 @@ Options:
 
 For information about the ``gin`` and ``gist`` indexes types consult :pg_docs:`PostgreSQL documentation 12.9. GiST and GIN Index Types <textsearch-indexes.html>`
 
+Example::
 
-Migrating from existing application
------------------------------------
-
-For existing application with data is provided :class:`~pg_fts.migrations.UpdateVectorOperation`, this will update the vector.
-
-``name``
-
-.. attribute:: UpdateVectorOperation.name
-
-Name of the model
+    class Migration(migrations.Migration)
+        dependencies = [
+            ('article', '0003_fts_create_field'),
+        ]
 
-``fts_vector``
+        operations = [
+            CreateFTSIndexOperation(
+                name='Article',
+                fts_vector='fts_index',
+                index='gin'
+            ),
+        ]
 
-.. attribute:: UpdateVectorOperation.fts_vector
 
-Name of the :class:`~pg_fts.fields.TSVectorField`
+Migrating from existing application
+-----------------------------------
 
+For existing application with data is provided :class:`~pg_fts.migrations.UpdateVectorOperation`, this will update the vector.
 
 Changing and Removing
 ---------------------
@@ -184,38 +188,15 @@ Removing Index
 
 For removing the index is provided :class:`~pg_fts.migrations.DeleteFTSIndexOperation`.
 
-``name``
-
-.. attribute:: DeleteFTSIndexOperation.name
-
-Name of the model
-
-``fts_vector``
-
-.. attribute:: DeleteFTSIndexOperation.fts_vector
-
-Name of the :class:`~pg_fts.fields.TSVectorField`
-
-The previous index type, important for regressions.
 
 ``index``
+---------
 
 .. attribute:: CreateFTSIndexOperation.index 
 
+The previous index type, important for regressions.
 
 Removing Trigger
 ****************
 
 For removing the index is provided :class:`~pg_fts.migrations.DeleteFTSTriggerOperation`.
-
-``name``
-
-.. attribute:: DeleteFTSTriggerOperation.name
-
-Name of the model
-
-``fts_vector``
-
-.. attribute:: DeleteFTSTriggerOperation.fts_vector
-
-Name of the :class:`~pg_fts.fields.TSVectorField`

docs/ranks.rst

@@ -0,0 +1,93 @@
+Ranking
+=======
+
+.. .. module:: pg_fts.ranks
+..    :synopsis: Built-in rank types.
+
+RankBase options
+****************
+
+The following arguments are available to all FTSRank types
+
+``lookup``
+----------
+
+.. attribute:: FTSRank.lookup
+
+The :class:`~pg_fts.fields.TSVectorField` and its available lookup's ``search``, ``isearch`` and ``tsquery``.
+
+Will raise exception if lookup isn't valid.
+
+.. seealso::
+
+    For :class:`~pg_fts.fields.TSVectorField` lookups check :doc:`TSVectorField lookups</tsvector_field>`
+
+``normalization``
+-----------------
+
+.. attribute:: FTSRank.normalization
+
+A list or tuple of integers with the normalization values, can be used a bit mask
+``[1,2]`` will be converted to ``1|2`` in sql.
+
+
+Accepted Values = 0, 1, 2, 4, 8, 16, 32
+
+Default is PostgresSQL function default.
+
+Will raise exception if ``normalization`` isn't valid.
+
+``weights``
+-----------
+
+.. attribute:: FTSRank.weights
+
+A list or tuple of integers/floats [D-weight, C-weight, B-weight, A-weight] with the weight values ``[0.1, 0.2, 0.4, 1]`` will be converted to ``{0.1, 0.2, 0.4, 1.0}`` in sql.
+
+Default is PostgresSQL function default.
+
+Will raise exception if ``weights`` isn't valid.
+
+.. seealso::
+    
+    More about ``normalization`` and ``weights`` check PostgreSQL documentation :pg_docs:`12.3.3. Ranking Search Results <textsearch-controls.html#TEXTSEARCH-RANKING>`
+
+
+``FTSRank``
+***********
+
+.. class:: FTSRank(**options)
+
+Uses PostgreSQL ``ts_rank`` function, ranks on frequency of matching lexemes.
+
+Examples:
+
+Search and order by rank::
+
+    Article.objects.annotate(
+        rank=(FTSRank(fts__search='once upon a time'))).order_by('-rank')
+
+Search and with normalization::
+
+    Article.objects.annotate(
+        normalized=(FTSRank(
+            fts__search='once upon a time',
+            noramlization=(1,2)
+        ))).order_by('-normalized')
+
+
+``FTSRankCd``
+*************
+
+.. class:: FTSRankCd(**options)
+
+Uses PostgreSQL ``ts_rank_cd`` function, ranks over cover density.
+
+Usage is the same as FTSRank, just with this class.
+
+Multiple dictionaries support
+*****************************
+
+For this case there are two classes ``FTSRankDictionay``, ``FTSRankCdDictionary``.
+
+The usage is the same as normal ``FTSRank`` or ``FTSRankCd``, was added the special support for lookups with dictionary transformation.