Merge #303

303: Improve docs, improve pylint config, and add type hints to `bork.api` r=duckinator a=duckinator



Co-authored-by: Ellen Marie Dash <me@duckie.co>

.pylintrc

@@ -20,12 +20,8 @@ enable=all
 
 # Disable the message, report, category or checker with the given id(s).
 disable=missing-docstring,
-        bad-whitespace,
-        bad-continuation,
-        len-as-condition,
         compare-to-zero,
         invalid-name,
-        no-else-return,
         consider-using-f-string,
         consider-iterating-dictionary,
         consider-using-with, # FIXME: re-enabling this is worth investigating

bork/api.py

@@ -23,11 +23,13 @@
 
 
 def aliases():
+    """Returns a list of the aliases defined in pyproject.toml."""
     pyproject = load_pyproject()
     return pyproject.get('tool', {}).get('bork', {}).get('aliases', {})
 
 
 def build():
+    """Build the project."""
     try:
         builder.dist()
         builder.zipapp()
@@ -57,6 +59,10 @@ def build():
 
 
 def clean():
+    """Removes artifacts generated by `bork clean`.
+
+    (Specifically: `./build`, `./dist`, and any `*.egg-info` files.)
+    """
     try_delete('./build')
     try_delete('./dist')
     for name in Path.cwd().glob('*.egg-info'):
@@ -65,11 +71,39 @@ def clean():
 
 
 def dependencies():
-    """Get the list of dependencies."""
+    """Returns the list of dependencies for the project."""
     return pep517.meta.load('.').metadata.get_all('Requires-Dist')
 
 
 def download(package, release_tag, file_pattern, directory):
+    """Saves files from the designated package, to the specified directory.
+
+    The format for `package` is `<SOURCE>:<NAME>`, where:
+
+    - `<SOURCE>` is one of: `gh`/`github`, `pypi`, or `testpypi`.
+    - `<NAME>` is the identifier for the package on the specified source.
+
+    E.g., Bork would be `gh:duckinator/bork` or `pypi:bork`.
+
+    **NOTE:** `pypi-test` is a deprecated alias of `testpypi`, and will be
+    removed in a future version.
+
+    Arguments:
+        package:
+            Package to download files for, in the format `<SOURCE>:<NAME>`.
+
+        release_tag:
+            The version or tag to download.
+
+        file_pattern:
+            Any files matching this pattern will be downloaded.
+
+            (Wildcards: `*` matches anything, `?` matches any single character.)
+
+        directory:
+            The directory where files are saved.
+            This directory is created, if needed.
+    """
     if file_pattern is None or len(file_pattern) == 0:
         raise ValueError('file_pattern must be non-empty.')
 
@@ -81,11 +115,21 @@ def download(package, release_tag, file_pattern, directory):
     if source not in DOWNLOAD_SOURCES.keys():
         raise ValueError('Invalid package/repository -- unknown source given.')
 
-    source = DOWNLOAD_SOURCES[source]
-    source.download(package, release_tag, file_pattern, directory)
+    downloader = DOWNLOAD_SOURCES[source]
+    downloader.download(package, release_tag, file_pattern, directory) # type:ignore
 
 
 def release(repository_name, dry_run):
+    """Uploads build artifacts to a PyPi instance or GitHub, as configured
+    in pyproject.toml.
+
+    Arguments:
+        repository_name:
+            The name of the PyPi repository. (You probably want 'pypi'.)
+
+        dry_run:
+            If True, don't actually release, just show what a release would do.
+    """
     pyproject = load_pyproject()
     bork_config = pyproject.get('tool', {}).get('bork', {})
     release_config = bork_config.get('release', {})
@@ -131,6 +175,7 @@ def release(repository_name, dry_run):
 
 
 def run(alias):
+    """Run the alias specified by `alias`, as defined in pyproject.toml."""
     pyproject = load_pyproject()
 
     try:

bork/cli.py

@@ -1,16 +1,17 @@
 """Command-line interface for Bork.
 
-General usage: `bork COMMAND [OPTIONS] [ARGS]`
+Usage:
+
+`bork COMMAND [OPTIONS] [ARGS]`
 
 Options that exist for all commands include:
 
 `--verbose`: enable verbose logging
 
 `--debug`: enable even more verbose logging (sometimes too noisy to be helpful)
 
-## Commands
+**Commands:**
 
-<dl>
 """
 
 import inspect

bork/filesystem.py

@@ -29,9 +29,8 @@ def load_pyproject():
                     'requires': ['setuptools>=42'],
                 },
             }
-        else:
-            # Can't figure out what kind of project it is.
-            raise
+        # Can't figure out what kind of project it is.
+        raise
 
 
 def find_files(globs):

docs/api.md

@@ -1,3 +1,3 @@
-# Bork API
+# bork.api
 
 ::: bork.api

mkdocs.yml

@@ -3,14 +3,17 @@ site_description: "Documentation for Bork, the build and release management tool
 repo_url: https://github.com/duckinator/bork
 edit_uri: blob/main/docs/
 
-nav:
-- Home: index.md
-- API: api.md
-
+# Enable search, and include documentation from docstrings.
 plugins:
 - search
 - mkdocstrings
 
+# Use the readthedocs theme, with syntax highlighting.
 theme:
   name: readthedocs
   highlightjs: true
+
+# Build PDF & ePub versions of docs.
+formats:
+  - epub
+  - pdf