Merge pull request #395 from twisted/384-cli-help

Use text from debian man pages for CLI help output.

src/towncrier/_settings/__init__.py

@@ -7,8 +7,15 @@
 ConfigError = load.ConfigError
 load_config_from_options = load.load_config_from_options
 
+# Help message for --config CLI option, shared by all sub-commands.
+config_option_help = (
+    "Pass a custom config file at FILE_PATH. "
+    "Default: towncrier.toml or pyproject.toml file, "
+    "if both files exist, the first will take precedence."
+)
 
 __all__ = [
+    "config_option_help",
     "load_config",
     "ConfigError",
     "load_config_from_options",

src/towncrier/_shell.py

@@ -2,7 +2,9 @@
 # See LICENSE for details.
 
 """
-towncrier, a builder for your news files.
+Entry point of the command line interface.
+
+Each sub-command has its separate CLI definition andd help messages.
 """
 
 import click
@@ -18,6 +20,22 @@
 @click.group(cls=DefaultGroup, default="build", default_if_no_args=True)
 @click.version_option(__version__.public())
 def cli():
+    """
+    Towncrier is a utility to produce useful, summarised news files for your project.
+    Rather than reading the Git history as some newer tools to produce it, or having
+    one single file which developers all write to, towncrier reads "news fragments"
+    which contain information useful to end users.
+
+    Towncrier delivers the news which is convenient to those that hear it, not those
+    that write it.
+
+    That is, a “news fragment” (a small file containing just enough information to
+    be useful to end users) can be written that summarises what has changed from the
+    “developer log” (which may contain complex information about the original issue,
+    how it was fixed, who authored the fix, and who reviewed the fix). By compiling
+    a collection of these fragments, towncrier can produce a digest of the changes
+    which is valuable to those who may wish to use the software.
+    """
     pass
 
 

src/towncrier/build.py

@@ -16,7 +16,11 @@
 from ._builder import find_fragments, render_fragments, split_fragments
 from ._git import remove_files, stage_newsfile
 from ._project import get_project_name, get_version
-from ._settings import ConfigError, load_config_from_options
+from ._settings import (
+    ConfigError,
+    config_option_help,
+    load_config_from_options,
+)
 from ._writer import append_to_newsfile
 
 
@@ -30,11 +34,31 @@ def _get_date():
     "draft",
     default=False,
     flag_value=True,
-    help="Render the news fragments, don't write to files, don't check versions.",
+    help=(
+        "Render the news fragments to standard output. "
+        "Don't write to files, don't check versions."
+    ),
+)
+@click.option(
+    "--config",
+    "config_file",
+    default=None,
+    metavar="FILE_PATH",
+    help=config_option_help,
+)
+@click.option(
+    "--dir",
+    "directory",
+    default=None,
+    metavar="PATH",
+    help="Build fragment in directory. Default to current directory.",
+)
+@click.option(
+    "--name",
+    "project_name",
+    default=None,
+    help="Pass a custom project name.",
 )
-@click.option("--config", "config_file", default=None, help="Configuration file name.")
-@click.option("--dir", "directory", default=None)
-@click.option("--name", "project_name", default=None)
 @click.option(
     "--version",
     "project_version",
@@ -58,6 +82,9 @@ def _main(
     project_date,
     answer_yes,
 ):
+    """
+    Build a combined news file from news fragment.
+    """
     try:
         return __main(
             draft,

src/towncrier/check.py

@@ -10,7 +10,7 @@
 import click
 
 from ._builder import find_fragments
-from ._settings import load_config_from_options
+from ._settings import config_option_help, load_config_from_options
 
 
 def _run(args, **kwargs):
@@ -19,10 +19,34 @@ def _run(args, **kwargs):
 
 
 @click.command(name="check")
-@click.option("--compare-with", default="origin/master")
-@click.option("--dir", "directory", default=None)
-@click.option("--config", "config", default=None)
+@click.option(
+    "--compare-with",
+    default="origin/master",
+    metavar="BRANCH",
+    help=(
+        "Checks files changed running git diff --name-ony BRANCH... "
+        "BRANCH is the branch to be compared with. "
+        "Default to origin/master"
+    ),
+)
+@click.option(
+    "--dir",
+    "directory",
+    default=None,
+    metavar="PATH",
+    help="Check fragment in directory. Default to current directory.",
+)
+@click.option(
+    "--config",
+    "config",
+    default=None,
+    metavar="FILE_PATH",
+    help=config_option_help,
+)
 def _main(compare_with, directory, config):
+    """
+    Check for new fragments on a branch.
+    """
     return __main(compare_with, directory, config)
 
 

src/towncrier/create.py

@@ -5,18 +5,29 @@
 Create a new fragment.
 """
 
-
 import os
 
 import click
 
-from ._settings import load_config_from_options
+from ._settings import config_option_help, load_config_from_options
 
 
 @click.command(name="create")
 @click.pass_context
-@click.option("--dir", "directory", default=None)
-@click.option("--config", "config", default=None)
+@click.option(
+    "--dir",
+    "directory",
+    default=None,
+    metavar="PATH",
+    help="Create fragment in directory. Default to current directory.",
+)
+@click.option(
+    "--config",
+    "config",
+    default=None,
+    metavar="FILE_PATH",
+    help=config_option_help,
+)
 @click.option(
     "--edit/--no-edit",
     default=False,
@@ -31,6 +42,20 @@
 )
 @click.argument("filename")
 def _main(ctx, directory, config, filename, edit, content):
+    """
+    Create a new news fragment.
+
+    Create a new news fragment called FILENAME or pass the full path for a file.
+    Towncrier has a few standard types of news fragments, signified by the file extension.
+
+    \b
+    These are:
+    * .feature - a new feature
+    * .bugfix - a bug fix
+    * .doc - a documentation improvement,
+    * .removal - a deprecation or removal of public API,
+    * .misc - a ticket has been closed, but it is not of interest to users.
+    """
     return __main(ctx, directory, config, filename, edit, content)
 
 

src/towncrier/newsfragments/384.doc

@@ -0,0 +1 @@
+The CLI help messages were updated to contain more information.