add mara_db click group

docs/api.rst

@@ -3,7 +3,7 @@ API
 
 .. module:: mara_db
 
-This part of the documentation covers all the interfaces of Mara Page. For
+This part of the documentation covers all the interfaces of Mara DB. For
 parts where the package depends on external libraries, we document the most
 important right here and provide links to the canonical documentation.
 

docs/cli.rst

@@ -0,0 +1,28 @@
+CLI
+===
+
+.. module:: mara_db.cli
+
+This part of the documentation covers all the available cli commands of Mara DB.
+
+
+``migrate``
+-----------
+
+.. tabs::
+
+    .. group-tab:: Mara CLI
+
+        .. code-block:: shell
+
+            mara db migrate
+
+    .. group-tab:: Mara Flask App
+
+        .. code-block:: python
+
+            flask mara-db migrate
+
+
+Compares the current database db alias `mara` with all defined models and applies
+the diff using alembic.

docs/index.rst

@@ -59,6 +59,17 @@ This section focuses on the supported database engines.
    dbs/SQLite
 
 
+CLI commands
+------------
+
+When you are looking at available CLI commands, here you are at the right place.
+
+.. toctree::
+   :maxdepth: 2
+
+   cli
+
+
 API Reference
 -------------
 
@@ -80,4 +91,4 @@ Legal information and changelog are here for the interested.
    :maxdepth: 2
 
    license
-   changes
+   changes

mara_db/__init__.py

@@ -23,7 +23,8 @@ def MARA_ACL_RESOURCES():
 
 def MARA_CLICK_COMMANDS():
     from . import cli
-    return [cli.migrate]
+    return [cli.mara_db,
+            cli._migrate]
 
 
 def MARA_NAVIGATION_ENTRIES():

mara_db/cli.py

@@ -1,14 +1,29 @@
 """Auto-migrate command line interface"""
 
+import click
 import sys
+from warnings import warn
 
-import click
 
+@click.group()
+def mara_db():
+    """Commands to interact with the database."""
+    pass
 
-@click.command()
+
+@mara_db.command()
 def migrate():
     """Compares the current database with all defined models and applies the diff"""
     import mara_db.auto_migration
 
     if not mara_db.auto_migration.auto_discover_models_and_migrate():
         sys.exit(-1)
+
+
+# Old cli commands to be dropped in 5.0:
+
+@click.command("migrate")
+def _migrate():
+    """Compares the current database with all defined models and applies the diff"""
+    warn("CLI command `<app> mara_db.migrate` will be dropped in 5.0. Please use: `<app> mara-db migrate`")
+    migrate.callback()