Adding missing docstrings to twine/commands (#799)

* Add missing docstrings

* Better docstrings

* Better docstrings

* Remove `twine/commands/*`

* Use reStructuredText style

* Fix linting error

* Fix a typo

Co-authored-by: Ian Stapleton Cordasco <[email protected]>

* Use reStructuredText/Sphinx directive

* Remove types from params

* Update high-level command docstrings

* Rewrite check docstring

* Rewrite register docstring

* Rewrite skip_existing docstring

* Rewrite upload docstring

* Simplify exceptions

* Restore deleted docstrings

Co-authored-by: Ian Stapleton Cordasco <[email protected]>
Co-authored-by: Brian Rutledge <[email protected]>

.flake8

@@ -13,5 +13,4 @@ per-file-ignores =
     # D103 Missing docstring in public function
     # D104 Missing docstring in public package
     twine/*: D100,D101,D102,D103,D104
-    twine/commands/*: D100,D101,D102,D103,D104
     tests/*: D100,D101,D102,D103,D104

twine/commands/__init__.py

@@ -1,3 +1,8 @@
+"""Module containing the logic for the ``twine`` sub-commands.
+
+The contents of this package are not a public API. For more details, see
+https://github.com/pypa/twine/issues/194 and https://github.com/pypa/twine/issues/665.
+"""
 # Copyright 2013 Donald Stufft
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

twine/commands/check.py

@@ -1,3 +1,4 @@
+"""Module containing the logic for ``twine check``."""
 # Copyright 2018 Dustin Ingram
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -106,6 +107,21 @@ def check(
     output_stream: IO[str] = sys.stdout,
     strict: bool = False,
 ) -> bool:
+    """Check that a distribution will render correctly on PyPI and display the results.
+
+    This is currently only validates ``long_description``, but more checks could be
+    added; see https://github.com/pypa/twine/projects/2.
+
+    :param dists:
+        The distribution files to check.
+    :param output_stream:
+        The destination of the resulting output.
+    :param strict:
+        If ``True``, treat warnings as errors.
+
+    :return:
+        ``True`` if there are rendering errors, otherwise ``False``.
+    """
     uploads = [i for i in commands._find_dists(dists) if not i.endswith(".asc")]
     if not uploads:  # Return early, if there are no files to check.
         output_stream.write("No files to check.\n")
@@ -146,6 +162,14 @@ def check(
 
 
 def main(args: List[str]) -> bool:
+    """Execute the ``check`` command.
+
+    :param args:
+        The command-line arguments.
+
+    :return:
+        The exit status of the ``check`` command.
+    """
     parser = argparse.ArgumentParser(prog="twine check")
     parser.add_argument(
         "dists",

twine/commands/register.py

@@ -1,3 +1,4 @@
+"""Module containing the logic for ``twine register``."""
 # Copyright 2015 Ian Cordasco
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -21,6 +22,21 @@
 
 
 def register(register_settings: settings.Settings, package: str) -> None:
+    """Pre-register a package name with a repository before uploading a distribution.
+
+    Pre-registration is not supported on PyPI, so the ``register`` command is only
+    necessary if you are using a different repository that requires it.
+
+    :param register_settings:
+        The configured options relating to repository registration.
+    :param package:
+        The path of the distribution to use for package metadata.
+
+    :raises twine.exceptions.TwineException:
+        The registration failed due to a configuration error.
+    :raises requests.HTTPError:
+        The repository responded with an error.
+    """
     repository_url = cast(str, register_settings.repository_config["repository"])
     print(f"Registering package to {repository_url}")
     repository = register_settings.create_repository()
@@ -45,6 +61,11 @@ def register(register_settings: settings.Settings, package: str) -> None:
 
 
 def main(args: List[str]) -> None:
+    """Execute the ``register`` command.
+
+    :param args:
+        The command-line arguments.
+    """
     parser = argparse.ArgumentParser(
         prog="twine register",
         description="register operation is not required with PyPI.org",

twine/commands/upload.py

@@ -1,3 +1,4 @@
+"""Module containing the logic for ``twine upload``."""
 # Copyright 2013 Donald Stufft
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -30,6 +31,20 @@
 def skip_upload(
     response: requests.Response, skip_existing: bool, package: package_file.PackageFile
 ) -> bool:
+    """Determine if a failed upload is an error or can be safely ignored.
+
+    :param response:
+        The response from attempting to upload ``package`` to a repository.
+    :param skip_existing:
+        If ``True``, use the status and content of ``response`` to determine if the
+        package already exists on the repository. If so, then a failed upload is safe
+        to ignore.
+    :param package:
+        The package that was being uploaded.
+
+    :return:
+        ``True`` if a failed upload can be safely ignored, otherwise ``False``.
+    """
     if not skip_existing:
         return False
 
@@ -75,6 +90,26 @@ def _make_package(
 
 
 def upload(upload_settings: settings.Settings, dists: List[str]) -> None:
+    """Upload one or more distributions to a repository, and display the progress.
+
+    If a package already exists on the repository, most repositories will return an
+    error response. However, if ``upload_settings.skip_existing`` is ``True``, a message
+    will be displayed and any remaining distributions will be uploaded.
+
+    For known repositories (like PyPI), the web URLs of successfully uploaded packages
+    will be displayed.
+
+    :param upload_settings:
+        The configured options related to uploading to a repository.
+    :param dists:
+        The distribution files to upload to the repository. This can also include
+        ``.asc`` files; the GPG signatures will be added to the corresponding uploads.
+
+    :raises twine.exceptions.TwineException:
+        The upload failed due to a configuration error.
+    :raises requests.HTTPError:
+        The repository responded with an error.
+    """
     dists = commands._find_dists(dists)
     # Determine if the user has passed in pre-signed distributions
     signatures = {os.path.basename(d): d for d in dists if d.endswith(".asc")}
@@ -135,6 +170,11 @@ def upload(upload_settings: settings.Settings, dists: List[str]) -> None:
 
 
 def main(args: List[str]) -> None:
+    """Execute the ``upload`` command.
+
+    :param args:
+        The command-line arguments.
+    """
     parser = argparse.ArgumentParser(prog="twine upload")
     settings.Settings.register_argparse_arguments(parser)
     parser.add_argument(