From df46eaa4cea1c1f710c1ae831ce15f2962ffc416 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Thu, 10 Oct 2024 15:32:49 +0200 Subject: [PATCH] Improve the documentation Signed-off-by: Carmen Bianca BAKKER --- README.md | 17 +++++++++++------ changelog.d/changed/click.md | 18 ++++++++++++++++-- docs/man/reuse-annotate.rst | 10 +++++----- docs/man/reuse-convert-dep5.rst | 2 +- docs/man/reuse-download.rst | 4 ++-- docs/man/reuse-lint-file.rst | 2 +- docs/man/reuse-lint.rst | 2 +- docs/man/reuse-spdx.rst | 2 +- docs/man/reuse-supported-licenses.rst | 2 +- docs/man/reuse.rst | 16 ++++------------ src/reuse/cli/annotate.py | 22 ++++++++++++++-------- src/reuse/cli/convert_dep5.py | 2 +- src/reuse/cli/download.py | 2 +- src/reuse/cli/lint.py | 11 ++++++----- src/reuse/cli/lint_file.py | 8 ++++---- src/reuse/cli/main.py | 1 + src/reuse/cli/spdx.py | 4 ++-- 17 files changed, 72 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 64ba00c1d..c772e9b34 100644 --- a/README.md +++ b/README.md @@ -270,13 +270,18 @@ repos: ### Shell completion -You can generate a shell completion script with `reuse --print-completion bash`. -Replace 'bash' as needed. You must place the printed text in a file dictated by -your shell to benefit from completions. +In order to enable shell completion, you need to generate the shell completion +script. You do this with `_REUSE_COMPLETE=bash_source reuse`. Replace `bash` +with `zsh` or `fish` as needed, or any other shells supported by the +Python`click` library. You can then source the output in your shell rc file, +like so (e.g.`~/.bashrc`): -This functionality depends on `shtab`, which is an optional dependency. To -benefit from this feature, install reuse with the `completion` extra, like -`pipx install reuse[completion]`. +```bash +eval "$(_REUSE__COMPLETE=bash_source reuse)" +``` + +Alternatively, you can place the generated completion script in +`${XDG_DATA_HOME}/bash-completion/completions/reuse`. ## Maintainers diff --git a/changelog.d/changed/click.md b/changelog.d/changed/click.md index fcb9830c1..bedc5e5a7 100644 --- a/changelog.d/changed/click.md +++ b/changelog.d/changed/click.md @@ -1,3 +1,17 @@ - Switched from `argparse` to `click` for handling the CLI. The CLI should still - handle identically, with identical options and arguments, but some stuff - changed under the hood. (#1084) + handle the same, with identical options and arguments, but some stuff changed + under the hood. (#1084) + + Find here a small list of differences: + + - `-h` is no longer shorthand for `--help`. + - `--version` now outputs "reuse, version X.Y.Z", followed by a licensing + blurb on different paragraphs. + - Some options are made explicitly mutually exclusive, such as `annotate`'s + `--skip-unrecognised` and `--style`, and `download`'s `--output` and + `--all`. + - Subcommands which take a list of things (files, license) as arguments, such + as `annotate`, `lint-file`, or `download`, now also allow zero arguments. + This will do nothing, but can be useful in scripting. + - `annotate` and `lint-file` now also take directories as arguments. This will + do nothing, but can be useful in scripting. diff --git a/docs/man/reuse-annotate.rst b/docs/man/reuse-annotate.rst index ae01e0af2..9a1795cb6 100644 --- a/docs/man/reuse-annotate.rst +++ b/docs/man/reuse-annotate.rst @@ -46,22 +46,22 @@ Mandatory options ----------------- At least *one* among the following options is required. They contain the -information which the tool will add to the file(s). +information which the tool will add to the file(s). You can repeat these +options. .. option:: -c, --copyright COPYRIGHT A copyright holder. This does not contain the year or the copyright prefix. See :option:`--year` and :option:`--copyright-prefix` for the year and prefix. - This option can be repeated. .. option:: -l, --license LICENSE - An SPDX license identifier. This option can be repeated. + An SPDX license identifier. .. option:: --contributor CONTRIBUTOR A name of a contributor. The contributor will be added via the - ``SPDX-FileContributor:`` tag. This option can be repeated. + ``SPDX-FileContributor:`` tag. Other options ------------- @@ -143,7 +143,7 @@ Other options Instead of aborting when a file extension does not have an associated comment style, skip those files. -.. option:: -h, --help +.. option:: --help Display help and exit. diff --git a/docs/man/reuse-convert-dep5.rst b/docs/man/reuse-convert-dep5.rst index 427344c2b..0be35935b 100644 --- a/docs/man/reuse-convert-dep5.rst +++ b/docs/man/reuse-convert-dep5.rst @@ -21,7 +21,7 @@ functionally equivalent ``REUSE.toml`` file in the root of the project. The Options ------- -.. option:: -h, --help +.. option:: --help Display help and exit. diff --git a/docs/man/reuse-download.rst b/docs/man/reuse-download.rst index 4c79f0fa3..88adc424d 100644 --- a/docs/man/reuse-download.rst +++ b/docs/man/reuse-download.rst @@ -36,11 +36,11 @@ Options If downloading a single file, output it to a specific file instead of putting it in a detected ``LICENSES/`` directory. -.. option:: --source SOURCE +.. option:: --source PATH Specify a source from which to copy custom ``LicenseRef-`` files. This can be a directory containing such file, or a path to the file itself. -.. option:: -h, --help +.. option:: --help Display help and exit. diff --git a/docs/man/reuse-lint-file.rst b/docs/man/reuse-lint-file.rst index 314cc46da..8e9487cb3 100644 --- a/docs/man/reuse-lint-file.rst +++ b/docs/man/reuse-lint-file.rst @@ -45,6 +45,6 @@ Options Output one line per error, prefixed by the file path. This option is the default. -.. option:: -h, --help +.. option:: --help Display help and exit. diff --git a/docs/man/reuse-lint.rst b/docs/man/reuse-lint.rst index 6c0cf6d77..03c66c2dd 100644 --- a/docs/man/reuse-lint.rst +++ b/docs/man/reuse-lint.rst @@ -97,6 +97,6 @@ Options Output one line per error, prefixed by the file path. -.. option:: -h, --help +.. option:: --help Display help and exit. diff --git a/docs/man/reuse-spdx.rst b/docs/man/reuse-spdx.rst index 46515dced..e6d5fb4e4 100644 --- a/docs/man/reuse-spdx.rst +++ b/docs/man/reuse-spdx.rst @@ -41,6 +41,6 @@ Options Name of the creator (organization) of the bill of materials. -.. option:: -h, --help +.. option:: --help Display help and exit. diff --git a/docs/man/reuse-supported-licenses.rst b/docs/man/reuse-supported-licenses.rst index 8dbb87596..902d171f3 100644 --- a/docs/man/reuse-supported-licenses.rst +++ b/docs/man/reuse-supported-licenses.rst @@ -25,6 +25,6 @@ full name of the license, and an URL to the license. Options ------- -.. option:: -h, --help +.. option:: --help Display help and exit. diff --git a/docs/man/reuse.rst b/docs/man/reuse.rst index 121b66144..e1b448c21 100644 --- a/docs/man/reuse.rst +++ b/docs/man/reuse.rst @@ -78,18 +78,7 @@ Options current working directory's VCS repository, or to the current working directory. -.. option:: -s, --print-completion SHELL - - Print a static shell completion script for the given shell and exit. You must - place the printed text in a file dictated by your shell before the completions - will function. For Bash, this file is - ``${XDG_DATA_HOME}/bash-completion/reuse``. - - This option depends on ``shtab``, which is an optional dependency of - :program:`reuse`. The supported shells depend on your installed version of - ``shtab``. - -.. option:: -h, --help +.. option:: --help Display help and exit. If no command is provided, this option is implied. @@ -112,6 +101,9 @@ Commands :manpage:`reuse-lint(1)` Verify whether a project is compliant with the REUSE Specification. +:manpage:`reuse-lint-file(1)` + Verify whether individual files are compliant with the REUSE Specification. + :manpage:`reuse-spdx(1)` Generate SPDX bill of materials. diff --git a/src/reuse/cli/annotate.py b/src/reuse/cli/annotate.py index f32fc9b31..3ba231ee9 100644 --- a/src/reuse/cli/annotate.py +++ b/src/reuse/cli/annotate.py @@ -121,8 +121,9 @@ def verify_paths_comment_style( "{}\n\n{}".format( _( "The following files do not have a recognised file" - " extension. Please use --style, --force-dot-license," - " --fallback-dot-license, or --skip-unrecognised:" + " extension. Please use '--style'," + " '--force-dot-license', '--fallback-dot-license', or" + " '--skip-unrecognised':" ), "\n".join(str(path) for path in unrecognised_files), ) @@ -153,14 +154,14 @@ def verify_paths_line_handling( raise click.UsageError( _( "'{path}' does not support single-line comments, please" - " do not use --single-line" + " do not use '--single-line'." ).format(path=path) ) if multi_line and not style.can_handle_multi(): raise click.UsageError( _( "'{path}' does not support multi-line comments, please" - " do not use --multi-line" + " do not use '--multi-line'." ).format(path=path) ) @@ -268,7 +269,7 @@ def get_reuse_info( ] _HELP = ( - _("Add copyright and licensing into the header of one or more" " files.") + _("Add copyright and licensing into the headers of files.") + "\n\n" + _( "By using --copyright and --license, you can specify which" @@ -290,9 +291,10 @@ def get_reuse_info( "--copyright", "-c", "copyrights", + metavar=_("COPYRIGHT"), type=str, multiple=True, - help=_("Copyright statement."), + help=_("Copyright statement, repeatable."), ) @click.option( "--license", @@ -301,21 +303,24 @@ def get_reuse_info( metavar=_("SPDX_IDENTIFIER"), type=spdx_identifier, multiple=True, - help=_("SPDX License Identifier."), + help=_("SPDX License Identifier, repeatable."), ) @click.option( "--contributor", "contributors", + metavar=_("CONTRIBUTOR"), type=str, multiple=True, - help=_("File contributor."), + help=_("File contributor, repeatable."), ) @click.option( "--year", "-y", "years", + metavar=_("YEAR"), cls=MutexOption, mutually_exclusive=_YEAR_MUTEX, + # TODO: This multiple behaviour is kind of word. Let's redo it. multiple=True, type=str, help=_("Year of copyright statement."), @@ -342,6 +347,7 @@ def get_reuse_info( "--template", "-t", "template_str", + metavar=_("TEMPLATE"), type=str, help=_("Name of template to use."), ) diff --git a/src/reuse/cli/convert_dep5.py b/src/reuse/cli/convert_dep5.py index f213bc33d..c7bec0263 100644 --- a/src/reuse/cli/convert_dep5.py +++ b/src/reuse/cli/convert_dep5.py @@ -30,7 +30,7 @@ def convert_dep5(obj: ClickObj) -> None: # pylint: disable=missing-function-docstring project = cast(Project, obj.project) if not (project.root / ".reuse/dep5").exists(): - raise click.UsageError(_("no '.reuse/dep5' file")) + raise click.UsageError(_("No '.reuse/dep5' file.")) text = toml_from_dep5( cast(ReuseDep5, project.global_licensing).dep5_copyright diff --git a/src/reuse/cli/download.py b/src/reuse/cli/download.py index a1d57b915..55d3998a9 100644 --- a/src/reuse/cli/download.py +++ b/src/reuse/cli/download.py @@ -136,7 +136,7 @@ def _successfully_downloaded(destination: StrPath) -> None: type=click.Path(exists=True, readable=True, path_type=Path), help=_( "Source from which to copy custom LicenseRef- licenses, either" - " a directory that contains the file or the file itself" + " a directory that contains the file or the file itself." ), ) @click.argument( diff --git a/src/reuse/cli/lint.py b/src/reuse/cli/lint.py index f4545081f..0509ce0df 100644 --- a/src/reuse/cli/lint.py +++ b/src/reuse/cli/lint.py @@ -14,6 +14,7 @@ import click +from .. import __REUSE_version__ from ..i18n import _ from ..lint import format_json, format_lines, format_plain from ..project import Project @@ -25,11 +26,11 @@ _HELP = ( _( - "Lint the project directory for compliance with" - " version {reuse_version} of the REUSE Specification. You can" - " find the latest version of the specification at" - " ." - ) + "Lint the project directory for REUSE compliance. This version of the" + " tool checks against version {reuse_version} of the REUSE" + " Specification. You can find the latest version of the specification" + " at ." + ).format(reuse_version=__REUSE_version__) + "\n\n" + _("Specifically, the following criteria are checked:") + "\n\n" diff --git a/src/reuse/cli/lint_file.py b/src/reuse/cli/lint_file.py index 7de7d83e1..b6e8bd81a 100644 --- a/src/reuse/cli/lint_file.py +++ b/src/reuse/cli/lint_file.py @@ -23,9 +23,9 @@ _OUTPUT_MUTEX = ["quiet", "lines"] _HELP = _( - "Lint individual files. The specified FILEs are checked for the presence" - " of copyright and licensing information, and whether the found licenses" - " are included in the LICENSES/ directory." + "Lint individual files for REUSE compliance. The specified FILEs are" + " checked for the presence of copyright and licensing information, and" + " whether the found licenses are included in the LICENSES/ directory." ) @@ -63,7 +63,7 @@ def lint_file( for file_ in subset_files: if not file_.resolve().is_relative_to(project.root.resolve()): raise click.UsageError( - _("'{file}' is not inside of '{root}'").format( + _("'{file}' is not inside of '{root}'.").format( file=file_, root=project.root ) ) diff --git a/src/reuse/cli/main.py b/src/reuse/cli/main.py index b2e2a9552..e85248906 100644 --- a/src/reuse/cli/main.py +++ b/src/reuse/cli/main.py @@ -45,6 +45,7 @@ " the Free Software Foundation, either version 3 of the License, or" " (at your option) any later version." ) + + "\n\n" + _( "This program is distributed in the hope that it will be useful," " but WITHOUT ANY WARRANTY; without even the implied warranty of" diff --git a/src/reuse/cli/spdx.py b/src/reuse/cli/spdx.py index 115dd25d9..9c69477bb 100644 --- a/src/reuse/cli/spdx.py +++ b/src/reuse/cli/spdx.py @@ -81,8 +81,8 @@ def spdx( ): raise click.UsageError( _( - "--creator-person=NAME or --creator-organization=NAME" - " required when --add-license-concluded is provided" + "'--creator-person' or '--creator-organization'" + " is required when '--add-license-concluded' is provided." ) )