docs: rewrite quick start section

docs/conf.py

@@ -265,4 +265,8 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("http://docs.python.org/", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
+    "sqlalchemy": ("https://docs.sqlalchemy.org/", None),
+    "sqlalchemy_utils": ("https://sqlalchemy-utils.readthedocs.io/en/latest/", None),
+}

docs/index.rst

@@ -2,22 +2,22 @@ SQLAlchemy-Searchable
 =====================
 
 
-SQLAlchemy-Searchable provides `full text search`_ capabilities for SQLAlchemy_ models. Currently it only supports PostgreSQL_.
+SQLAlchemy-Searchable provides `full text search`_ capabilities for SQLAlchemy_ models. Currently, it only supports PostgreSQL_.
 
 
 .. toctree::
    :maxdepth: 2
 
-   installation
+   quickstart
    search_query_parser
    configuration
    vectorizers
    alembic_migrations
    integrations
 
 
-.. _`full text search`: http://en.wikipedia.org/wiki/Full_text_search
-.. _SQLAlchemy: http://http://www.sqlalchemy.org/
-.. _PostgreSQL: http://www.postgresql.org/
+.. _`full text search`: https://en.wikipedia.org/wiki/Full_text_search
+.. _SQLAlchemy: https://www.sqlalchemy.org/
+.. _PostgreSQL: https://www.postgresql.org/
 
 

docs/quickstart.rst

@@ -0,0 +1,98 @@
+Quick start
+===========
+
+Installation
+------------
+
+SQLAlchemy-Searchable is available on PyPI_. It can be installed using pip_::
+
+    pip install SQLAlchemy-Searchable
+
+SQLAlchemy-Searchable requires Python 3.8 or newer, either the cPython or PyPy
+implementation.
+
+.. _PyPI: https://pypi.python.org/pypi/SQLAlchemy-Searchable
+.. _pip: https://pip.pypa.io/
+
+Configuration
+-------------
+
+The first step to enable full-text search functionality in your app is to
+configure SQLAlchemy-Searchable using :func:`make_searchable` function by
+passing it your declarative base class::
+
+    from sqlalchemy.orm import declarative_base
+    from sqlalchemy_searchable import make_searchable
+
+    Base = declarative_base()
+    make_searchable(Base.metadata)
+
+Define models
+-------------
+
+Then, add a search vector column to your model and specify which columns you want to
+be included in the full-text search. Here's an example using an ``Article``
+model::
+
+    from sqlalchemy import Column, Integer, String, Text
+    from sqlalchemy_utils.types import TSVectorType
+
+    class Article(Base):
+        __tablename__ = "article"
+
+        id = Column(Integer, primary_key=True)
+        name = Column(String(255))
+        content = Column(Text)
+        search_vector = Column(TSVectorType("name", "content"))
+
+The search vector is a special column of
+:class:`~sqlalchemy_utils.types.ts_vector.TSVectorType` data type that is
+optimized for text search. Here, we want the ``name`` and ``content`` columns to
+be full-text indexed, which we have indicated by giving them as arguments to the
+:class:`~sqlalchemy_utils.types.ts_vector.TSVectorType` constructor.
+
+Create and populate the tables
+------------------------------
+
+Now, let's create the tables and add some sample data. Before creating the
+tables, make sure to call :func:`sqlalchemy.orm.configure_mappers` to ensure
+that mappers have been configured for the models::
+
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import configure_mappers, Session
+
+    engine = create_engine("postgresql://localhost/sqlalchemy_searchable_test")
+    configure_mappers()  # IMPORTANT!
+    Base.metadata.create_all(engine)
+
+    session = Session(engine)
+
+    article1 = Article(name="First article", content="This is the first article")
+    article2 = Article(name="Second article", content="This is the second article")
+
+    session.add(article1)
+    session.add(article2)
+    session.commit()
+
+Performing searches
+-------------------
+
+After we've created the articles and populated the database, we can now perform
+full-text searches on them using the :func:`~sqlalchemy_searchable.search`
+function::
+
+    from sqlalchemy_searchable import search
+
+    query = session.query(Article)
+    query = search(query, "first")
+
+    print(query.first().name)
+    # Output: First article
+
+API
+---
+
+.. module:: sqlalchemy_searchable
+.. autofunction:: make_searchable
+.. autofunction:: search
+

sqlalchemy_searchable/__init__.py

@@ -44,7 +44,10 @@ def search(query, search_query, vector=None, regconfig=None, sort=False):
     :param search_query: the search query
     :param vector: search vector to use
     :param regconfig: postgresql regconfig to be used
-    :param sort: order results by relevance (quality of hit)
+    :param sort: Order the results by relevance. This uses `cover density`_ ranking
+        algorithm (``ts_rank_cd``) for sorting.
+
+    .. _cover density: https://www.postgresql.org/docs/devel/textsearch-controls.html#TEXTSEARCH-RANKING
     """
     if not search_query.strip():
         return query