add howto docs for command list order in helps fix #116

Author: bckohan

django_typer/management/__init__.py

@@ -588,6 +588,10 @@ class Command(TyperCommand):
             @command(cls=CustomCommand)
             def handle(self):
                 ...
+
+
+    See `click commands api <https://click.palletsprojects.com/en/latest/api/#commands>`_
+    for more information.
     """
 
 
@@ -610,6 +614,10 @@ class Command(TyperCommand):
             @group(cls=CustomGroup)
             def grp(self):
                 ...
+
+    See `click docs on custom groups <https://click.palletsprojects.com/en/latest/commands/#custom-groups>`_
+    and `advanced patterns <https://click.palletsprojects.com/en/latest/advanced/>`_ for more
+    information.
     """
 
     def list_commands(self, ctx: click.Context) -> t.List[str]:

doc/source/changelog.rst

@@ -12,6 +12,7 @@ v2.2.3 (2024-10-xx)
 * Completed `Open up vulnerability reporting and add security policy. <https://github.com/django-commons/django-typer/issues/124>`_
 * Completed `Move architecture in docs to ARCHITECTURE.md <https://github.com/django-commons/django-typer/issues/121>`_
 * Completed `Transfer to django-commons <https://github.com/django-commons/django-typer/issues/117>`_
+* Completed `Add howto for how to change the display order of commands in help. <https://github.com/django-commons/django-typer/issues/116>`_
 
 v2.2.2 (2024-08-25)
 ====================

doc/source/howto.rst

@@ -650,7 +650,43 @@ value:
         Docstring will be used as help.
         """
 
+Order Commands in Help Text
+---------------------------
+
+**By default commands are listed in the order they appear in the class**. You can override
+this by
+`using a custom click group <https://click.palletsprojects.com/en/latest/commands/#custom-groups>`_.
+
+For example, to change the order of commands to be in reverse alphabetical order you could define
+a custom group and override the ``list_commands`` method. Custom group and command classes may be
+provided like below, but they must extend from django-typer's classes:
+
+* For groups: :class:`~django_typer.management.DTGroup`
+* For commands: :class:`~django_typer.management.DTCommand`
+
+.. tabs::
+
+    .. tab:: Django-style
+
+        .. literalinclude:: ../../tests/apps/howto/management/commands/order.py
+
+    .. tab:: Typer-style
+
+        .. literalinclude:: ../../tests/apps/howto/management/commands/order_typer.py
+
+.. tabs::
+
+    .. tab:: Default Order
+
+        .. typer:: tests.apps.howto.management.commands.order_default.Command:typer_app
+            :prog: ./manage.py order
+            :width: 80
+
+    .. tab:: Alphabetized
 
+        .. typer:: tests.apps.howto.management.commands.order.Command:typer_app
+            :prog: ./manage.py order
+            :width: 80
 
 Document Commands w/Sphinx
 --------------------------

tests/apps/howto/management/commands/order.py

@@ -3,32 +3,32 @@
 from click import Context
 
 
-class ReverseAlphaCommands(DTGroup):
+class AlphabetizeCommands(DTGroup):
     def list_commands(self, ctx: Context) -> t.List[str]:
-        return list(sorted(self.commands.keys(), reverse=True))
+        return list(sorted(self.commands.keys()))
 
 
-class Command(TyperCommand, cls=ReverseAlphaCommands):
-    @command()
-    def a(self):
-        print("a")
-
+class Command(TyperCommand, cls=AlphabetizeCommands):
     @command()
     def b(self):
         print("b")
 
     @command()
-    def c(self):
-        print("c")
+    def a(self):
+        print("a")
 
-    @group(cls=ReverseAlphaCommands)
+    @group(cls=AlphabetizeCommands)
     def d(self):
         print("d")
 
+    @d.command()
+    def f(self):
+        print("f")
+
     @d.command()
     def e(self):
         print("e")
 
-    @d.command()
-    def f(self):
-        print("f")
+    @command()
+    def c(self):
+        print("c")

tests/apps/howto/management/commands/order_default.py

@@ -0,0 +1,5 @@
+from .order import Command as Order
+
+
+class Command(Order):
+    pass

tests/apps/howto/management/commands/order_typer.py

@@ -1,43 +1,44 @@
 from django_typer.management import Typer, DTGroup
 from click import Context
+import typing as t
 
 
-class ReverseAlphaCommands(DTGroup):
-    def list_commands(self, ctx: Context) -> list[str]:
-        return list(sorted(self.commands.keys(), reverse=True))
+class AlphabetizeCommands(DTGroup):
+    def list_commands(self, ctx: Context) -> t.List[str]:
+        return list(sorted(self.commands.keys()))
 
 
-app = Typer(cls=ReverseAlphaCommands)
+app = Typer(cls=AlphabetizeCommands)
 
-d_app = Typer(cls=ReverseAlphaCommands)
+d_app = Typer(cls=AlphabetizeCommands)
 app.add_typer(d_app)
 
 
-@app.command()
-def a():
-    print("a")
-
-
 @app.command()
 def b():
     print("b")
 
 
 @app.command()
-def c():
-    print("c")
+def a():
+    print("a")
 
 
-@d_app.callback(cls=ReverseAlphaCommands)
+@d_app.callback()
 def d():
     print("d")
 
 
+@d_app.command()
+def f():
+    print("f")
+
+
 @d_app.command()
 def e():
     print("e")
 
 
-@d_app.command()
-def f():
-    print("f")
+@app.command()
+def c():
+    print("c")

tests/test_howto.py

@@ -313,9 +313,9 @@ class TestPrintingTyperHowto(TestPrintingHowto):
 class TestOrderHowTo(TestCase):
     cmd = "order"
 
-    from tests.apps.howto.management.commands.order import ReverseAlphaCommands
+    from tests.apps.howto.management.commands.order import AlphabetizeCommands
 
-    grp_cls = ReverseAlphaCommands
+    grp_cls = AlphabetizeCommands
 
     def test_howto_order(self):
         from tests.apps.howto.management.commands.order import Command as OrderCommand
@@ -331,18 +331,18 @@ def test_howto_order(self):
 
         if rich_installed:
             self.assertTrue(
-                hlp.index("│ d")
-                < hlp.index("│ c")
+                hlp.index("│ a")
                 < hlp.index("│ b")
-                < hlp.index("│ a")
+                < hlp.index("│ c")
+                < hlp.index("│ d")
             )
         else:
             cmd_idx = hlp.index("Commands")
             self.assertTrue(
-                hlp.index(" d", cmd_idx)
-                < hlp.index(" c", cmd_idx)
+                hlp.index(" a", cmd_idx)
                 < hlp.index(" b", cmd_idx)
-                < hlp.index(" a", cmd_idx)
+                < hlp.index(" c", cmd_idx)
+                < hlp.index(" d", cmd_idx)
             )
 
         buffer.seek(0)
@@ -352,15 +352,15 @@ def test_howto_order(self):
         hlp = buffer.getvalue()
 
         if rich_installed:
-            self.assertTrue(hlp.index("│ f") < hlp.index("│ e"))
+            self.assertTrue(hlp.index("│ e") < hlp.index("│ f"))
         else:
             cmd_idx = hlp.index("Commands")
-            self.assertTrue(hlp.index(" f", cmd_idx) < hlp.index(" e", cmd_idx))
+            self.assertTrue(hlp.index(" e", cmd_idx) < hlp.index(" f", cmd_idx))
 
 
 class TestPrintingTyperHowto(TestOrderHowTo):
     cmd = "order_typer"
 
-    from tests.apps.howto.management.commands.order_typer import ReverseAlphaCommands
+    from tests.apps.howto.management.commands.order_typer import AlphabetizeCommands
 
-    grp_cls = ReverseAlphaCommands
+    grp_cls = AlphabetizeCommands