diff --git a/src/towncrier/_settings/__init__.py b/src/towncrier/_settings/__init__.py index 6cbe32a2..2eb48803 100644 --- a/src/towncrier/_settings/__init__.py +++ b/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", diff --git a/src/towncrier/_shell.py b/src/towncrier/_shell.py index f550003f..fd916ab4 100644 --- a/src/towncrier/_shell.py +++ b/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 diff --git a/src/towncrier/build.py b/src/towncrier/build.py index 61848498..a59b13cf 100644 --- a/src/towncrier/build.py +++ b/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, diff --git a/src/towncrier/check.py b/src/towncrier/check.py index 0c0d5b0a..67f8ed72 100644 --- a/src/towncrier/check.py +++ b/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) diff --git a/src/towncrier/create.py b/src/towncrier/create.py index 616bad3f..fe909cb7 100644 --- a/src/towncrier/create.py +++ b/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) diff --git a/src/towncrier/newsfragments/384.doc b/src/towncrier/newsfragments/384.doc new file mode 100644 index 00000000..49e9c008 --- /dev/null +++ b/src/towncrier/newsfragments/384.doc @@ -0,0 +1 @@ +The CLI help messages were updated to contain more information.