Doc improvements (#1962)

* Remove CHANGELOG from search results
* Simplify the section on why tortoise was built
* Improve databases and router pages

Author: henadzit

CHANGELOG.rst

@@ -1,4 +1,5 @@
 .. _changelog:
+:no-search:
 
 =========
 Changelog

README.rst

@@ -31,16 +31,9 @@ Tortoise ORM supports CPython 3.9 and later for SQLite, MySQL, PostgreSQL, Micro
 Why was Tortoise ORM built?
 ---------------------------
 
-Python has many existing and mature ORMs, unfortunately they are designed with an opposing paradigm of how I/O gets processed.
-``asyncio`` is relatively new technology that has a very different concurrency model, and the largest change is regarding how I/O is handled.
+Tortoise ORM was built to provide a lightweight, async-native Object-Relational Mapper for Python with a familiar Django-like API.
 
-However, Tortoise ORM is not the first attempt of building an ``asyncio`` ORM. While there are many cases of developers attempting to map synchronous Python ORMs to the async world, initial attempts did not have a clean API.
-
-Hence we started Tortoise ORM.
-
-Tortoise ORM is designed to be functional, yet familiar, to ease the migration of developers wishing to switch to ``asyncio``.
-
-It also performs well when compared to other Python ORMs. In `our benchmarks <https://github.com/tortoise/orm-benchmarks>`_, where we measure different read and write operations (rows/sec, more is better), it's trading places with Pony ORM:
+Tortoise ORM performs well when compared to other Python ORMs. In `our benchmarks <https://github.com/tortoise/orm-benchmarks>`_, where we measure different read and write operations (rows/sec, more is better), it's trading places with Pony ORM:
 
 .. image:: https://raw.githubusercontent.com/tortoise/tortoise-orm/develop/docs/ORM_Perf.png
     :target: https://github.com/tortoise/orm-benchmarks

docs/databases.rst

@@ -18,9 +18,7 @@ To use, please ensure that corresponding asyncio driver is installed.
 DB_URL
 ======
 
-Tortoise supports specifying Database configuration in a URL form.
-
-The form is:
+Tortoise supports specifying Database configuration in a URL form. The form is:
 
 :samp:`{DB_TYPE}://{USERNAME}:{PASSWORD}@{HOST}:{PORT}/{DB_NAME}?{PARAM1}=value&{PARAM2}=value`
 

docs/index.rst

@@ -18,16 +18,9 @@ Introduction
 Why was Tortoise ORM built?
 ---------------------------
 
-Python has many existing and mature ORMs, unfortunately they are designed with an opposing paradigm of how I/O gets processed.
-``asyncio`` is relatively new technology that has a different concurrency model, and the largest change is regarding how I/O is handled.
+Tortoise ORM was built to provide a lightweight, async-native Object-Relational Mapper for Python with a familiar Django-like API.
 
-However, Tortoise ORM is not first attempt of building ``asyncio`` ORM, there are many cases of developers attempting to map synchronous python ORMs to the async world, initial attempts did not have a clean API.
-
-Hence we started Tortoise ORM.
-
-Tortoise ORM is designed to be functional, yet familiar, to ease the migration of developers wishing to switch to ``asyncio``.
-
-It also performs well when compared to other Python ORMs. In `our benchmarks <https://github.com/tortoise/orm-benchmarks>`_, where we measure different read and write operations (rows/sec, more is better), it's trading places with Pony ORM:
+Tortoise ORM performs well when compared to other Python ORMs. In `our benchmarks <https://github.com/tortoise/orm-benchmarks>`_, where we measure different read and write operations (rows/sec, more is better), it's trading places with Pony ORM:
 
 .. image:: ORM_Perf.png
     :target: https://github.com/tortoise/orm-benchmarks

docs/router.rst

@@ -4,15 +4,15 @@
 Router
 ======
 
-The easiest way to use multiple databases is to set up a database routing scheme. The default routing scheme ensures that objects remain 'sticky' to their original database (i.e., an object retrieved from the foo database will be saved on the same database). The default routing scheme ensures that if a database isn't specified, all queries fall back to the default database.
+The easiest way to use multiple databases is to set up a database routing scheme. The default routing scheme ensures that objects remain 'sticky' to their original database (i.e., an object retrieved from the foo database will be saved to the same database). The default routing scheme also ensures that if a database isn't specified, all queries fall back to the default database.
 
 Usage
 =====
 
 Define Router
 -------------
 
-Define a router is simple, you need just write a class that has `db_for_read` and `db_for_write` methods.
+Defining a router is simple - you just need to write a class that has `db_for_read` and `db_for_write` methods.
 
 .. code-block:: python3
 
@@ -23,19 +23,22 @@ Define a router is simple, you need just write a class that has `db_for_read` an
         def db_for_write(self, model: Type[Model]):
             return "master"
 
-The two methods return a connection string defined in configuration.
+Both methods return a connection identifier that must be defined in the Tortoise configuration.
 
-Config Router
--------------
+Configure Router
+----------------
 
-Just put it in configuration of tortoise or in `Tortoise.init` method.
+Simply include the router in your Tortoise configuration or pass it to the `Tortoise.init` method.
 
 .. code-block:: python3
 
-    config = {
-        "connections": {"master": "sqlite:///tmp/test.db", "slave": "sqlite:///tmp/test.db"},
+    CONFIG = {
+        "connections": {
+            "master": "sqlite:///tmp/m.db",
+            "slave": "sqlite:///tmp/s.db",
+        },
         "apps": {
-            "models": {
+            "app": {
                 "models": ["__main__"],
                 "default_connection": "master",
             }
@@ -44,9 +47,7 @@ Just put it in configuration of tortoise or in `Tortoise.init` method.
         "use_tz": False,
         "timezone": "UTC",
     }
-    await Tortoise.init(config=config)
-    # or
-    routers = config.pop('routers')
-    await Tortoise.init(config=config, routers=routers)
+    await Tortoise.init(config=CONFIG)
+
 
-After that, all `select` operations will use `slave` connection, all `create/update/delete` operations will use `master` connection.
+With this configuration, all `select` operations will use the `slave` connection, while all `create/update/delete` operations will use the `master` connection.

docs/setup.rst

@@ -4,55 +4,78 @@ Set up
 
 .. _init_app:
 
-Init app
-========
+Initialize Your Application
+===========================
 
-After you defined all your models, tortoise needs you to init them, in order to create backward relations between models and match your db client with appropriate models.
+After defining all your models, Tortoise ORM requires initialization to create backward relations between models and match your database client with the appropriate models.
 
-You can do it like this:
+You can initialize your application like this:
 
 .. code-block:: python3
 
     from tortoise import Tortoise
 
     async def init():
         # Here we create a SQLite DB using file "db.sqlite3"
-        #  also specify the app name of "models"
-        #  which contain models from "app.models"
+        # and specify the app name "models"
+        # which contains models from "app.models"
         await Tortoise.init(
             db_url='sqlite://db.sqlite3',
-            modules={'models': ['app.models']}
+            modules={'app': ['app.models']}
         )
         # Generate the schema
         await Tortoise.generate_schemas()
-    
-    
-Here we create connection to SQLite database client and then we discover & initialize models.
 
-``generate_schema`` generates schema on empty database, you shouldn't run it on every app init, run it just once, maybe out of your main code.
-There is also the option when generating the schemas to set the ``safe`` parameter to ``True`` which will only insert the tables if they don't already exist.
 
-If you define the variable ``__models__`` in the ``app.models`` module (or wherever you specify to load your models from), ``generate_schema`` will use that list, rather than automatically finding models for you.
+This example creates a connection to a SQLite database client and then discovers and initializes your models. The example configures the ``app`` application to load models from the ``app.models`` module. In this example it is a single application, but you can use multiple applications to group models.
 
-.. _cleaningup:
+The ``generate_schemas()`` method generates the database schema on an empty database. When generating schemas, you can set the ``safe`` parameter to ``True``, which will only create tables if they don't already exist:
+
+.. code-block:: python3
+
+    await Tortoise.generate_schemas(safe=True)
 
-The Importance of cleaning up
-=============================
+See :ref:`migration` for schema migration tools.
 
-Tortoise ORM will keep connections open to external Databases. As an ``asyncio`` Python library, it needs to have the connections closed properly or the Python interpreter may still wait for the completion of said connections.
+If you define a ``__models__`` variable in your ``app.models`` module (or wherever you specify to load your models from), ``generate_schemas()`` will use that list instead of automatically discovering models.
 
-To ensure connections are closed please ensure that ``Tortoise.close_connections()`` is called:
+Another way of initializing the application is to use the ``Tortoise.init()`` method with the ``config`` parameter.
 
 .. code-block:: python3
 
-    await Tortoise.close_connections()
+    CONFIG = {
+        "connections": {
+            "default": {
+                "engine": "tortoise.backends.sqlite",
+                "credentials": {"file_path": "default.sqlite3"},
+            },
+            "another_conn": {
+                "engine": "tortoise.backends.sqlite",
+                "credentials": {"file_path": "another_conn.sqlite3"},
+            },
+        },
+        "apps": {
+            "app": {"models": ["app.models"], "default_connection": "default"},
+            "another_app": {"models": ["another_app.models"], "default_connection": "another_conn"},
+        },
+    }
+
+    await Tortoise.init(config=CONFIG)
+
 
-The small helper function ``tortoise.run_async()`` will ensure that connections are closed.
+This way of initializing the application is useful when you want to configure different databases for different applications. This also allows to configure connection routing, see :ref:`router` for more details. Also check out :ref:`contrib_fastapi`, :ref:`contrib_sanic` and documentation on other integrations.
 
-Reference
-=========
+.. _cleaningup:
+
+The Importance of Cleaning Up
+=================================
+
+Tortoise ORM maintains open connections to external databases. As an ``asyncio``-based Python library, these connections must be closed properly, or the Python interpreter may continue waiting for their completion.
+
+To ensure connections are properly closed, make sure to call ``Tortoise.close_connections()``:
 
-.. automodule:: tortoise
-    :members:
-    :undoc-members:
+.. code-block:: python3
+
+    await Tortoise.close_connections()
 
+The helper function ``tortoise.run_async()`` automatically ensures that connections are closed when your application terminates.