Merge pull request #7700 from kenjis/docs-migration.rst

docs: improve migration.rst

Author: kenjis

user_guide_src/source/dbmgmt/migration.rst

@@ -9,9 +9,9 @@ need to go and run them. You would also have to keep track of which changes
 need to be run against the production machines next time you deploy.
 
 The database table **migrations** tracks which migrations have already been
-run so all you have to do is make sure your migrations are in place and
-call ``$migration->latest()`` to bring the database up to the most recent
-state. You can also use ``$migration->setNamespace(null)->latest()`` to
+run, so all you have to do is make sure your migrations are in place and
+run the ``spark migrate`` command to bring the database up to the most recent
+state. You can also use ``spark migrate --all`` to
 include migrations from all namespaces.
 
 .. contents::
@@ -94,23 +94,14 @@ This will look for any migrations located at both **APPPATH/Database/Migrations*
 **ROOTPATH/MyCompany/Database/Migrations**. This makes it simple to include migrations in your
 re-usable, modular code suites.
 
-*************
-Usage Example
-*************
-
-In this example some simple code is placed in **app/Controllers/Migrate.php**
-to update the schema:
-
-.. literalinclude:: migration/005.php
-
 .. _command-line-tools:
 
 *******************
 Command-Line Tools
 *******************
 
 CodeIgniter ships with several :doc:`commands </cli/spark_commands>` that are available from the command line to help
-you work with migrations. These tools are not required to use migrations but might make things easier for those of you
+you work with migrations. These tools make things easier for those of you
 that wish to use them. The tools primarily provide access to the same methods that are available within the MigrationRunner class.
 
 migrate
@@ -171,6 +162,9 @@ status
 Displays a list of all migrations and the date and time they ran, or '--' if they have not been run::
 
   > php spark migrate:status
+
+  ...
+
   +----------------------+-------------------+-----------------------+---------+---------------------+-------+
   | Namespace            | Version           | Filename              | Group   | Migrated On         | Batch |
   +----------------------+-------------------+-----------------------+---------+---------------------+-------+
@@ -194,13 +188,17 @@ creates is the Pascal case version of the filename.
 
   > php spark make:migration <class> [options]
 
-You can use (make:migration) with the following options:
+You can use (``make:migration``) with the following options:
+
+- ``--namespace`` - Set root namespace. Default: ``APP_NAMESPACE``.
+- ``--suffix``    - Append the component title to the class name.
+
+The following options are also available to generate the migration file for
+database sessions:
 
 - ``--session``   - Generates the migration file for database sessions.
 - ``--table``     - Table name to use for database sessions. Default: ``ci_sessions``.
 - ``--dbgroup``   - Database group to use for database sessions. Default: ``default``.
-- ``--namespace`` - Set root namespace. Default: ``APP_NAMESPACE``.
-- ``--suffix``    - Append the component title to the class name.
 
 *********************
 Migration Preferences
@@ -229,7 +227,7 @@ Class Reference
         :returns:    An array of migration files
         :rtype:    array
 
-        An array of migration filenames are returned that are found in the **path** property.
+        An array of migration filenames are returned that are found in the ``path`` property.
 
     .. php:method:: latest($group)
 
@@ -259,7 +257,7 @@ Class Reference
         :returns:    ``true`` on success, ``false`` on failure
         :rtype:    bool
 
-        This forces a single file to migrate regardless of order or batches. Method "up" or "down" is detected based on whether it has already been migrated.
+        This forces a single file to migrate regardless of order or batches. Method ``up()`` or ``down()`` is detected based on whether it has already been migrated.
 
         .. note:: This method is recommended only for testing and could cause data consistency issues.