Improve the documentation

Signed-off-by: Carmen Bianca BAKKER <[email protected]>

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
 

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.

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.
 

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.
 

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.

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.

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.

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.

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.

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.
 

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."),
 )

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

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(

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"
-        " <https://reuse.software/spec/>."
-    )
+        "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 <https://reuse.software/spec/>."
+    ).format(reuse_version=__REUSE_version__)
     + "\n\n"
     + _("Specifically, the following criteria are checked:")
     + "\n\n"

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
                 )
             )

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"

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."
             )
         )