docs: start adding docstrings to functions

I don't have enough energy to do this for all functions, but I'll try
to add some docs as I look at the code. The project is growing and it's
harder to remember what all the parts do.

rust2rpm/__main__.py

@@ -175,6 +175,7 @@ def download(crate, version):
 
 @contextlib.contextmanager
 def files_from_crate(cratef, crate, version):
+    """Unpacks cratef and returns path to toml file, list of doc files, list of license files"""
     with tempfile.TemporaryDirectory() as tmpdir:
         target_dir = f"{tmpdir}/"
         with tarfile.open(cratef, "r") as archive:
@@ -182,8 +183,7 @@ def files_from_crate(cratef, crate, version):
                 if not os.path.abspath(os.path.join(target_dir, n)).startswith(target_dir):
                     raise Exception("Unsafe filenames!")
             archive.extractall(target_dir)
-        toml_relpath = f"{crate}-{version}/Cargo.toml"
-        toml = f"{tmpdir}/{toml_relpath}"
+        toml = f"{tmpdir}/{crate}-{version}/Cargo.toml"
         if not os.path.isfile(toml):
             raise IOError("crate does not contain Cargo.toml file")
         root_path = f"{tmpdir}/{crate}-{version}"
@@ -192,6 +192,7 @@ def files_from_crate(cratef, crate, version):
         yield toml, doc_files, license_files
 
 def make_patch(toml, enabled=True, tmpfile=False):
+    """Spawns editor on toml and returns a unified diff after editor closes"""
     if not enabled:
         return []
 
@@ -225,6 +226,7 @@ def _is_path(path):
 
 @sortify
 def get_license_files(path):
+    """Heuristic match on file names to detect license files"""
     exclude = { "vendor", "example", "examples", "_example", "_examples",
                 "testdata", "_testdata", ".github", "tests", "test" }
     for root, dirs, files in os.walk(path, topdown=True):
@@ -235,6 +237,7 @@ def get_license_files(path):
 
 @sortify
 def get_doc_files(path):
+    """Heuristic match on file names to detect documentation files"""
     plus = re.compile(r"""
         .*\.(?:md|markdown|mdown|mkdn|rst|txt)|AUTHORS|
         AUTHORS[.-].*|CONTRIBUTORS|CONTRIBUTORS[.-].*|README|
@@ -250,6 +253,18 @@ def get_doc_files(path):
                 yield os.path.relpath(os.path.join(root, f), path)
 
 def get_package_info(package):
+    """Download information about package from dist-git.
+
+    Returns JSON with package metadata, or None if the package is
+    unnkown or the spec file is not present.
+
+    >>> rust2rpm.__main__.get_package_info('rust-alacritty')
+    {...
+    'name': 'rust-alacritty',
+    'namespace': 'rpms',
+    ...}
+    """
+
     url = requests.compat.urljoin(DIST_GIT_URL, f"rpms/{package}")
     req = requests.get(url, headers={"User-Agent": "rust2rpm"})
     json = req.json()
@@ -306,6 +321,12 @@ def to_list(s):
     return list(filter(None, (l.strip() for l in s.splitlines())))
 
 def detect_rpmautospec(default_target, spec_file):
+    """Guess whether %autorelease+%autochangelog should be used
+
+    Returns False if we're not on Fedora or if the spec file exists and
+    wasn't using rpmautospec already.
+    """
+
     # We default to on only for selected distros for now…
     if default_target not in {"fedora"}:
         return False