finish howto, fix help precedence bug, fix doc8 linting

Author: bckohan

.github/workflows/lint.yml

@@ -42,7 +42,8 @@ jobs:
           poetry run black django_typer --check
           poetry run pylint django_typer
           poetry run mypy django_typer
-          poetry run doc8 -q doc
           poetry check
           poetry run pip check
           poetry run python -m readme_renderer ./README.rst -o /tmp/README.html
+          cd ./doc
+          poetry run doc8 --ignore-path build --max-line-length 100

CONTRIBUTING.rst

@@ -7,6 +7,7 @@
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _readthedocs: https://readthedocs.org/
 .. _me: https://github.com/bckohan
+.. _black: https://black.readthedocs.io/en/stable/
 
 Contributing
 ############
@@ -37,30 +38,31 @@ Documentation
 
 `django-typer` documentation is generated using Sphinx_ with the
 readthedocs_ theme. Any new feature PRs must provide updated documentation for
-the features added. To build the docs run:
+the features added. To build the docs run doc8 to check for formatting issues
+then run Sphinx_:
 
-.. code-block::
+.. code-block:: bash
 
     cd ./doc
+    poetry run doc8 --ignore-path build --max-line-length 100
     poetry run make html
 
 
 Static Analysis
 ---------------
 
 `django-typer` uses Pylint_ for python linting and mypy_ for static type
-checking. Header imports are also standardized using isort_. Before any PR is
-accepted the following must be run, and static analysis tools should not
-produce any errors or warnings. Disabling certain errors or warnings where
-justified is acceptable:
+checking. Header imports are also standardized using isort_ and formatting is
+done with black_. Before any PR is accepted the following must be run, and
+static analysis tools should not produce any errors or warnings. Disabling
+certain errors or warnings where justified is acceptable:
 
-.. code-block::
+.. code-block:: bash
 
     poetry run isort django_typer
     poetry run black django_typer
     poetry run pylint django_typer
     poetry run mypy django_typer
-    poetry run doc8 -q doc
     poetry check
     poetry run pip check
     poetry run python -m readme_renderer ./README.rst

django_typer/__init__.py

@@ -962,12 +962,12 @@ def decorator(func: CommandFunctionType):
         setattr(
             func,
             "_typer_command_",
-            lambda cmd, _name=None, **extra: cmd.typer_app.command(
+            lambda cmd, _name=None, _help=None, **extra: cmd.typer_app.command(
                 name=name or _name,
                 *args,
                 cls=type("_AdaptedCommand", (cls,), {"django_command": cmd}),
                 context_settings=context_settings,
-                help=help,
+                help=help or _help,
                 epilog=epilog,
                 short_help=short_help,
                 options_metavar=options_metavar,
@@ -1290,7 +1290,11 @@ def get_ctor(attr: str) -> t.Optional[t.Callable[..., t.Any]]:
                 if cmd_cls._handle:
                     ctor = get_ctor(cmd_cls._handle)
                     if ctor:
-                        ctor(cls, _name=cls.typer_app.info.name)
+                        ctor(
+                            cls,
+                            _name=cls.typer_app.info.name,
+                            _help=getattr(cls, "help", None),
+                        )
                     else:
                         cls._num_commands += 1
                         cls.typer_app.command(

django_typer/tests/test_app/management/commands/help_precedence7.py

@@ -0,0 +1,19 @@
+import json
+
+from django.utils.translation import gettext_lazy as _
+
+from django_typer import TyperCommand, command
+
+
+class Command(TyperCommand):
+
+    help = _("Test minimal TyperCommand subclass - class member")
+
+    @command()
+    def handle(self, arg1: str, arg2: str, arg3: float = 0.5, arg4: int = 1):
+        """
+        Test minimal TyperCommand subclass - docstring
+        """
+        assert self.__class__ == Command
+        opts = {"arg1": arg1, "arg2": arg2, "arg3": arg3, "arg4": arg4}
+        return json.dumps(opts)

django_typer/tests/test_app/management/commands/help_precedence8.py

@@ -0,0 +1,18 @@
+import json
+
+from django.utils.translation import gettext_lazy as _
+
+from django_typer import TyperCommand, command
+
+
+class Command(TyperCommand, help=_("Test minimal TyperCommand subclass - typer param")):
+
+    help = _("Test minimal TyperCommand subclass - class member")
+
+    def handle(self, arg1: str, arg2: str, arg3: float = 0.5, arg4: int = 1):
+        """
+        Test minimal TyperCommand subclass - docstring
+        """
+        assert self.__class__ == Command
+        opts = {"arg1": arg1, "arg2": arg2, "arg3": arg3, "arg4": arg4}
+        return json.dumps(opts)

django_typer/tests/tests.py

@@ -935,6 +935,22 @@ def test_help_precedence6(self):
             "Test minimal TyperCommand subclass - docstring", buffer.getvalue()
         )
 
+    def test_help_precedence7(self):
+        buffer = StringIO()
+        cmd = get_command("help_precedence7", stdout=buffer, no_color=True)
+        cmd.print_help("./manage.py", "help_precedence7")
+        self.assertIn(
+            "Test minimal TyperCommand subclass - class member", buffer.getvalue()
+        )
+
+    def test_help_precedence8(self):
+        buffer = StringIO()
+        cmd = get_command("help_precedence8", stdout=buffer, no_color=True)
+        cmd.print_help("./manage.py", "help_precedence8")
+        self.assertIn(
+            "Test minimal TyperCommand subclass - typer param", buffer.getvalue()
+        )
+
 
 class TestOverloaded(TestCase):
     """

doc/.readthedocs.yaml

@@ -20,3 +20,7 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: doc/source/conf.py
+   
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf

doc/source/howto.rst

@@ -16,7 +16,7 @@ For example to define an integer positional argument we could simply do:
         ...
 
 You will likely want to add additional meta information to your arguments for Typer_ to render
-things like helps and usage strings.  You can do this by annotating the type hint with 
+things like helps and usage strings.  You can do this by annotating the type hint with
 the `typer.Argument` class:
 
 .. code-block::
@@ -25,7 +25,7 @@ the `typer.Argument` class:
     from typer import Argument
 
     # ...
-    
+
     def handle(self, int_arg: t.Annotated[int, Argument(help="An integer argument")]):
         ...
 
@@ -75,12 +75,12 @@ To add meta information, we annotate with the `typer.Option` class:
     from typer import Option
 
     # ...
-    
+
     def handle(self, name: t.Annotated[str, Option(help="The name of the thing")]):
         ...
 
 .. tip::
-    
+
     Refer to the Typer_ docs on options_ for more details.
 
 
@@ -248,11 +248,11 @@ This is like defining a group at the command root and is an extension of the
 Call TyperCommands from Code
 ----------------------------
 
-There are two options for invoking a :class:`~django_typer.TyperCommand` from code without spawning off
-a subprocess. The first is to use Django_'s builtin call_command_ function. This function will work exactly
-as it does for normal BaseCommand_ derived commands. django-typer_ however adds another mechanism that
-can be more efficient, especially if your options and arguments are already of the correct type and require
-no parsing:
+There are two options for invoking a :class:`~django_typer.TyperCommand` from code without spawning
+off a subprocess. The first is to use Django_'s builtin call_command_ function. This function will
+work exactly as it does for normal BaseCommand_ derived commands. django-typer_ however adds
+another mechanism that can be more efficient, especially if your options and arguments are already
+of the correct type and require no parsing:
 
 Say we have this command, called ``mycommand``:
 
@@ -287,8 +287,8 @@ Say we have this command, called ``mycommand``:
 The rule of them is this:
 
     - Use call_command_ if your options and arguments need parsing.
-    - Use :func:`~django_typer.get_command` and invoke the command functions directly if your options
-      and arguments are already of the correct type.
+    - Use :func:`~django_typer.get_command` and invoke the command functions directly if your
+      options and arguments are already of the correct type.
 
 .. tip::
 
@@ -300,13 +300,14 @@ Change Default Django Options
 -----------------------------
 
 :class:`~django_typer.TyperCommand` classes preserve all of the functionality of BaseCommand_ derivatives.
-This means that you can still use class members like `suppressed_base_arguments 
+This means that you can still use class members like `suppressed_base_arguments
 <https://docs.djangoproject.com/en/5.0/howto/custom-management-commands/#django.core.management.BaseCommand.suppressed_base_arguments>`_
 to suppress default options.
 
-By default :class:`~django_typer.TyperCommand` suppresses ``--verbosity``. You can add it back by setting 
-``suppressed_base_arguments`` to an empty list. If you want to use verbosity you can simply redefine it or
-use one of django-typer_'s :ref:`provided type hints <types>` for the default BaseCommand_ options:
+By default :class:`~django_typer.TyperCommand` suppresses ``--verbosity``. You can add it back by
+setting ``suppressed_base_arguments`` to an empty list. If you want to use verbosity you can
+simply redefine it or use one of django-typer_'s :ref:`provided type hints <types>` for the default
+BaseCommand_ options:
 
 .. code-block:: python
 
@@ -326,7 +327,7 @@ Configure the Typer_ Application
 
 Typer_ apps can be configured using a number of parameters. These parameters are usually passed
 to the Typer class constructor when the application is created. django-typer_ provides a way to
-pass these options upstream to Typer_ by supplying them as keyword arguments to the 
+pass these options upstream to Typer_ by supplying them as keyword arguments to the
 :class:`~django_typer.TyperCommand` class inheritance:
 
 .. code-block:: python
@@ -358,12 +359,12 @@ See the section on :ref:`defining shell completions.<define-shellcompletions>`
 Configure rich_ Stack Traces
 ----------------------------
 
-When rich_ is installed it may be `configured to display rendered stack traces 
+When rich_ is installed it may be `configured to display rendered stack traces
 <https://rich.readthedocs.io/en/stable/traceback.html>`_ for unhandled exceptions.
-These stack traces are information dense and can be very helpful for debugging. By default, if rich_
-is installed django-typer_ will configure it to render stack traces. You can disable this behavior by
-setting the ``DT_RICH_TRACEBACK_CONFIG`` config to ``False``. You may also set 
-``DT_RICH_TRACEBACK_CONFIG`` to a dictionary holding the parameters to pass to
+These stack traces are information dense and can be very helpful for debugging. By default, if
+rich_ is installed django-typer_ will configure it to render stack traces. You can disable
+this behavior by setting the ``DT_RICH_TRACEBACK_CONFIG`` config to ``False``. You may also
+set ``DT_RICH_TRACEBACK_CONFIG`` to a dictionary holding the parameters to pass to
 `rich.traceback.install`.
 
 This provides a common hook for configuring rich_ that you can control on a per-deployment basis:
@@ -397,6 +398,30 @@ This provides a common hook for configuring rich_ that you can control on a per-
     the Typer_ application. It is best to not set these and allow users to configure tracebacks
     via the ``DT_RICH_TRACEBACK_CONFIG`` setting.
 
+Add Help Text to Commands
+-------------------------
+
+There are multiple places to add help text to your commands. There is however a precedence order,
+and while lazy translation is supported in help texts, if you use docstrings as the helps they will
+not be translated.
+
+The precedence order, for a simple command is as follows:
+
+    .. code-block:: python
+
+        from django_typer import TyperCommand, command
+        from django.utils.translation import gettext_lazy as _
+
+        class Command(TyperCommand, help=_('2')):
+
+            help = _("3")
+
+            @command(help=_("1"))
+            def handle(self):
+                """
+                Docstring is last priority and is not subject to translation.
+                """
+
 
 Document Commands w/Sphinx
 --------------------------

doc/source/index.rst

@@ -17,7 +17,8 @@ BaseCommand functionality is preserved, so that TyperCommand can be a drop in re
    * Configure the rendering of exception stack traces using rich.
    * :ref:`Install shell tab-completion support <shellcompletions>` for TyperCommands and normal
      Django_ commands for bash_, zsh_, fish_ and powershell_.
-   * :ref:`Create custom and portable shell tab-completions for your CLI parameters. <define-shellcompletions>`
+   * :ref:`Create custom and portable shell tab-completions for your CLI parameters.
+     <define-shellcompletions>`
    * Refactor existing management commands into TyperCommands because TyperCommand is interface
      compatible with BaseCommand.