add cli docs with sphinx-click (#82)

This adds auto-generated docs for the wsinfer cli. This commit also
renames the subcommand cli function names, to account for
click-contrib/sphinx-click#74

docs/cli.rst

@@ -0,0 +1,3 @@
+.. click:: wsinfer.cli.cli:cli
+   :prog: wsinfer
+   :nested: full

docs/conf.py

@@ -17,6 +17,7 @@
     "sphinx.ext.intersphinx",  # for links
     "sphinx.ext.napoleon",  # for google style docstrings
     "autoapi.extension",  # to document the wsinfer api
+    "sphinx_click",  # to document click command line
 ]
 
 autoapi_type = "python"

docs/index.rst

@@ -27,6 +27,7 @@ on whole slide images.
 
    Installing <installing>
    User Guide <user_guide>
+   CLI <cli>
 
 
 .. |img-tissue| image:: images/brca-tissue.png

docs/requirements.txt

@@ -1,2 +1,3 @@
 pydata-sphinx-theme
 sphinx-autoapi
+sphinx-click

setup.cfg

@@ -61,6 +61,7 @@ docs =
     pydata-sphinx-theme
     sphinx
     sphinx-autoapi
+    sphinx-click
 
 [options.entry_points]
 console_scripts =

wsinfer/cli/cli.py

@@ -1,11 +1,11 @@
 import click
 
 # from .. import __version__
-from .convert_csv_to_geojson import cli as _cli_convert_to_geojson
-from .convert_csv_to_sbubmi import cli as _cli_convert_to_sbubmi
-from .infer import cli as _cli_inference
-from .list_models_and_weights import cli as _cli_list_models_weights
-from .patch import cli as _cli_patch
+from .convert_csv_to_geojson import togeojson
+from .convert_csv_to_sbubmi import tosbu
+from .infer import run
+from .list_models_and_weights import list
+from .patch import patch
 
 
 # We use invoke_without_command=True so that 'wsinfer' on its own can be used for
@@ -17,8 +17,8 @@ def cli():
     pass
 
 
-cli.add_command(_cli_inference, name="run")
-cli.add_command(_cli_convert_to_geojson, name="togeojson")
-cli.add_command(_cli_convert_to_sbubmi, name="tosbu")
-cli.add_command(_cli_patch, name="patch")
-cli.add_command(_cli_list_models_weights, name="list")
+cli.add_command(run)
+cli.add_command(togeojson)
+cli.add_command(tosbu)
+cli.add_command(patch)
+cli.add_command(list)

wsinfer/cli/convert_csv_to_geojson.py

@@ -78,7 +78,7 @@ def convert(input, output) -> None:
     "output",
     type=click.Path(exists=False, path_type=Path, resolve_path=True),
 )
-def cli(*, results_dir: Path, output: Path):
+def togeojson(*, results_dir: Path, output: Path):
     """Convert model outputs to GeoJSON format.
 
     GeoJSON files can be used with pathology viewers like QuPath.

wsinfer/cli/convert_csv_to_sbubmi.py

@@ -278,7 +278,7 @@ def get_color(row: pd.Series):
     default=4,
     help="Number of processes to use when `--make-color-text` is enabled.",
 )
-def cli(
+def tosbu(
     *,
     results_dir: Path,
     output: Path,

wsinfer/cli/infer.py

@@ -238,7 +238,7 @@ def get_stdout(args) -> str:
     help="Use a dense grid of patch coordinates. Patches will be present even if no"
     " tissue is present",
 )
-def cli(
+def run(
     ctx: click.Context,
     *,
     wsi_dir: Path,

wsinfer/cli/list_models_and_weights.py

@@ -4,7 +4,7 @@
 
 
 @click.command()
-def cli():
+def list():
     """Show all available models and weights."""
     models_weights = models.list_all_models_and_weights()
 

wsinfer/cli/patch.py

@@ -35,7 +35,7 @@
     type=float,
     help="Patch spacing in micrometers per pixel.",
 )
-def cli(
+def patch(
     source: str,
     step_size: Optional[int],
     patch_size: int,