Bug 1888339 Update doc on creating new mach commands. r=firefox-build-system-reviewers,sergesanspaille

Update the doc with the newer category, description, and MACH_COMMANDS requirements.

Differential Revision: https://phabricator.services.mozilla.com/D206034

python/mach/docs/commands.rst

@@ -38,16 +38,33 @@ Here is a complete example:
 .. rstcheck: ignore-languages=python
 .. code-block:: python
 
-    from mach.decorators import (
-      CommandArgument,
-      Command,
-    )
+   from mach.decorators import Command, CommandArgument
 
-    @Command('doit', help='Do ALL OF THE THINGS.')
+    @Command('doit', category='testing', description='Do ALL OF THE THINGS.')
     @CommandArgument('--force', '-f', action='store_true',
         help='Force doing it.')
     def doit(command_context, force=False):
         # Do stuff here.
+        print("hello world")
+
+All paths are relative to the root source folder.
+
+Save your file somewhere e.g. ``testing/doit.py``.
+
+Add an entry for your command in ``python/mach/mach/command_util.py`` in
+the `MACH_COMMANDS` dictionary. Maintain the alphabetical order.
+
+e.g
+
+.. code-block:: python
+
+    MACH_COMMANDS = {
+        # ... previous entries here
+        "doctor": MachCommandReference("python/mozbuild/mozbuild/mach_commands.py"),
+        "doit": MachCommandReference("testing/doit.py"),
+        "environment": MachCommandReference("python/mozbuild/mozbuild/mach_commands.py"),
+        # ... rest of entries here
+    }
 
 When the module is loaded, the decorators tell mach about all handlers.
 When mach runs, it takes the assembled metadata from these handlers and
@@ -89,9 +106,9 @@ Here is an example:
       """The build needs to be available."""
       return cls.build_path is not None
 
-  @Command('run_tests', conditions=[build_available])
-  def run_tests(command_context):
-      # Do stuff here.
+   @Command('run_tests', category='testing', description='A description.' conditions=[build_available])
+   def run_tests(command_context):
+       # Do stuff here.
 
 By default all commands without any conditions applied will be runnable,
 but it is possible to change this behaviour by setting