cli.py: Document commands

cinematinator/cli.py

+"""
+This is the main entrypoint to our project's code.
+
+See the subcommands' --help options for more specific help.
+"""
 import enum
 from typing import Dict, TextIO
 
@@ -19,6 +24,11 @@ from cinematinator.types import OfflineSolverProtocol
 
 @click.group()
 def cli() -> None:
+    """
+    This is the main entrypoint to our project's code.
+
+    See the following subcommands' --help for usage.
+    """
     pass
 
 
@@ -26,10 +36,12 @@ def cli() -> None:
 @click.argument("input_file", type=click.File(mode="r"))
 def print_instance_cmd(input_file: TextIO) -> None:
     """
-    Read a Cinema instance from the given file, then pretty-print it with the debug
-    character set.
+    Debug: Read and pretty-print a Cinema instance.
 
-    Pass '-' as the file to read from standard input (which lets you paste in a Cinema).
+    Pass '-' as the filename to read from standard input (which lets you paste in a
+    Cinema).
+
+    Debug command.
     """
 
     cinema = parse_cinema(input_file)
@@ -47,12 +59,20 @@ class OfflineSolvers(enum.Enum):
     "solver_name",
     type=click.Choice(OfflineSolvers._member_names_),  # type:ignore
     default="mip",
+    help="Undocumented debug option",
 )
 @click.argument("input_file", type=click.File(mode="r"))
 def offline_cmd(solver_name: str, input_file: TextIO) -> None:
     """
-    Read a Cinema instance from the given file and the group counts in this file, then
-    solve with an offline solver.
+    Read offline instance, solve using MIP.
+
+    Reads a Cinema instance and group counts from a file, then solves the problem for
+    this Cinema and group counts using an offline solver, either a MIP solver.
+
+    Pass '-' as the filename to read from standard input instead of a file.
+
+    For debugging an undocumented bruteforce solver is selectable using `--solver
+    bruteforce`, this will not work for most instances.
     """
 
     solver = OfflineSolvers[solver_name].value
@@ -70,8 +90,15 @@ def offline_cmd(solver_name: str, input_file: TextIO) -> None:
 @click.argument("input_file", type=click.File(mode="r"))
 def edge_algo_cmd(input_file: TextIO) -> None:
     """
-    Read a Cinema instance from the given file and the group counts in this file, then
-    solve with the edge algorithm.
+    Read offline instance, solve using combinatorial algorithm.
+
+    Reads a Cinema instance from the given file and the group counts in this file, then
+    solves this instance with the combinatorial / edge algorithm.
+
+    The only output will be the number of people that can optimally be seated for the
+    input.
+
+    Pass '-' as the input filename to read from standard input instead of a file.
     """
 
     cinema = parse_cinema(input_file)
@@ -101,7 +128,13 @@ def edge_algo_cmd(input_file: TextIO) -> None:
 )
 def online_cmd(input_file: TextIO, mode_name: str, print_when_done: bool) -> None:
     """
-    Solve an instance of the online variant of the problem.
+    Read online instance, solve using chosen strategy.
+
+    Reads a Cinema instance from the given file and initialized a Cinema object, then
+    repeatedly read group sizes from the input and attempt to seat each read group
+    before moving on to the next group.
+
+    Pass '-' as the input filename to read from standard input instead of a file.
 
     Currently the following modes are supported with --mode:
 
@@ -112,9 +145,10 @@ def online_cmd(input_file: TextIO, mode_name: str, print_when_done: bool) -> Non
           Fit groups in the rightmost position in the bottom row where the group fits.
       - "greedy":
           Fit groups in a position where they cause a minimum amount of still-available
-          seats to be blocked.
+          seats to be blocked. Also called "best-fit" in our paper.
       - "center":
           Try to fit groups as closest to the center of the cinema as possible.
+          Not described in our paper.
     """
 
     cinema = parse_cinema(input_file)