documentation command

Author: Corentin

CLI_Documentation.md

@@ -0,0 +1,108 @@
+# `MyoQuant`
+
+MyoQuant Analysis Command Line Interface
+
+**Usage**:
+
+```console
+$ MyoQuant [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `docs`: Generate documentation
+* `he-analysis`: Run the HE analysis and quantification on...
+* `sdh-analysis`: Run the SDH analysis and quantification on...
+
+## `MyoQuant docs`
+
+Generate documentation
+
+**Usage**:
+
+```console
+$ MyoQuant docs [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `generate`: Generate markdown version of usage...
+
+### `MyoQuant docs generate`
+
+Generate markdown version of usage documentation
+
+**Usage**:
+
+```console
+$ MyoQuant docs generate [OPTIONS]
+```
+
+**Options**:
+
+* `--name TEXT`: The name of the CLI program to use in docs.
+* `--output FILE`: An output file to write docs to, like README.md.
+* `--help`: Show this message and exit.
+
+## `MyoQuant he-analysis`
+
+Run the HE analysis and quantification on the image.
+
+**Usage**:
+
+```console
+$ MyoQuant he-analysis [OPTIONS] IMAGE_PATH
+```
+
+**Arguments**:
+
+* `IMAGE_PATH`: The HE image file path to analyse. If using single channel images, this will be used as cytoplasm image to run CellPose. Please use the --fluo-nuc option to indicate the path to the nuclei single image to run Stardist.  [required]
+
+**Options**:
+
+* `--mask-path FILE`: The path to a binary mask to hide slide region during analysis. It needs to be of the same resolution as input image and only pixel marked as 1 will be analyzed.
+* `--cellpose-path FILE`: The pre-computed CellPose mask to use for analysis. Will run Cellpose if no path provided. Required as an image file.
+* `--stardist-path FILE`: The pre-computed Stardist mask to use for analysis. Will run Stardist if no path provided. Required as an image file.
+* `--output-path PATH`: The path to the folder to save the results. Will save in the same folder as input image if not specified.
+* `--cellpose-diameter INTEGER`: Approximative single cell diameter in pixel for CellPose detection. If not specified, Cellpose will try to deduce it.
+* `--nms-thresh FLOAT RANGE`: NMS Threshold for Stardist nuclei detection.  [default: 0.4; 0<=x<=1]
+* `--prob-thresh FLOAT RANGE`: Probability Threshold for Stardist nuclei detection.  [default: 0.5; 0.5<=x<=1]
+* `--eccentricity-thresh FLOAT RANGE`: Eccentricity threshold value for a nucleus to be considered as internalized during nuclei classification. When very close to 1 almost all nuclei are considered as internalized.  [default: 0.75; 0<=x<=1]
+* `--export-map / --no-export-map`: Export the original image with cells painted by classification label.  [default: export-map]
+* `--export-stats / --no-export-stats`: Export per fiber and per nuclei stat table.  [default: export-stats]
+* `--fluo-nuc FILE`: The path to single channel fluo image for nuclei.
+* `--help`: Show this message and exit.
+
+## `MyoQuant sdh-analysis`
+
+Run the SDH analysis and quantification on the image.
+
+**Usage**:
+
+```console
+$ MyoQuant sdh-analysis [OPTIONS] IMAGE_PATH
+```
+
+**Arguments**:
+
+* `IMAGE_PATH`: The image file path to analyse.  [required]
+
+**Options**:
+
+* `--mask-path FILE`: The path to a binary mask to hide slide region during analysis. It needs to be of the same resolution as input image and only pixel marked as 1 will be analyzed.
+* `--model-path FILE`: The SDH model path to use for analysis. Will download latest one if no path provided.
+* `--cellpose-path FILE`: The pre-computed CellPose mask to use for analysis. Will run Cellpose if no path provided. Required as an image file.
+* `--output-path PATH`: The path to the folder to save the results. Will save in the current folder if not specified.
+* `--cellpose-diameter INTEGER`: Approximative single cell diameter in pixel for CellPose detection. If not specified, Cellpose will try to deduce it.
+* `--export-map / --no-export-map`: Export the original image with cells painted by classification label.  [default: export-map]
+* `--export-stats / --no-export-stats`: Export per fiber stat table.  [default: export-stats]
+* `--help`: Show this message and exit.
+

README.md

@@ -33,6 +33,8 @@ Using pip, you can simply install MyoQuant in a python environment with a simple
 To use the command-line tool, first activate your venv in which MyoQuant is installed: `source .venv/bin/activate`  
 Then you can perform SDH or HE analysis. You can use the command `myoquant --help` to list available commands.
 
+## 💡Full command documentation is avaliable here: [CLI Documentation](https://github.com/lambda-science/MyoQuant/blob/main/CLI_Documentation.md)
+
 - **For SDH Image Analysis** the command is:  
   `myoquant sdh-analysis IMAGE_PATH`  
   Don't forget to run `myoquant sdh-analysis --help` for information about options.

myoquant/__main__.py

@@ -15,6 +15,10 @@
     pretty_exceptions_show_locals=False,
 )
 
+from .utils.docs import app as docs_app
+
+app.add_typer(docs_app, name="docs", help="Generate documentation")
+
 
 @app.command()
 def sdh_analysis(

myoquant/utils/docs.py

@@ -0,0 +1,113 @@
+from pathlib import Path
+from typing import cast
+
+import typer
+import typer.core
+from click import Command, Group
+
+
+app = typer.Typer()
+
+
+def get_docs_for_click(
+    *,
+    obj: Command,
+    ctx: typer.Context,
+    indent: int = 0,
+    name: str = "",
+    call_prefix: str = "",
+) -> str:
+    docs = "#" * (1 + indent)
+    command_name = name or obj.name
+    if call_prefix:
+        command_name = f"{call_prefix} {command_name}"
+    title = f"`{command_name}`" if command_name else "CLI"
+    docs += f" {title}\n\n"
+    if obj.help:
+        docs += f"{obj.help}\n\n"
+    usage_pieces = obj.collect_usage_pieces(ctx)
+    if usage_pieces:
+        docs += "**Usage**:\n\n"
+        docs += "```console\n"
+        docs += "$ "
+        if command_name:
+            docs += f"{command_name} "
+        docs += f"{' '.join(usage_pieces)}\n"
+        docs += "```\n\n"
+    args = []
+    opts = []
+    for param in obj.get_params(ctx):
+        rv = param.get_help_record(ctx)
+        if rv is not None:
+            if param.param_type_name == "argument":
+                args.append(rv)
+            elif param.param_type_name == "option":
+                opts.append(rv)
+    if args:
+        docs += "**Arguments**:\n\n"
+        for arg_name, arg_help in args:
+            docs += f"* `{arg_name}`"
+            if arg_help:
+                docs += f": {arg_help}"
+            docs += "\n"
+        docs += "\n"
+    if opts:
+        docs += "**Options**:\n\n"
+        for opt_name, opt_help in opts:
+            docs += f"* `{opt_name}`"
+            if opt_help:
+                docs += f": {opt_help}"
+            docs += "\n"
+        docs += "\n"
+    if obj.epilog:
+        docs += f"{obj.epilog}\n\n"
+    if isinstance(obj, Group):
+        group: Group = cast(Group, obj)
+        commands = group.list_commands(ctx)
+        if commands:
+            docs += "**Commands**:\n\n"
+            for command in commands:
+                command_obj = group.get_command(ctx, command)
+                assert command_obj
+                docs += f"* `{command_obj.name}`"
+                command_help = command_obj.get_short_help_str()
+                if command_help:
+                    docs += f": {command_help}"
+                docs += "\n"
+            docs += "\n"
+        for command in commands:
+            command_obj = group.get_command(ctx, command)
+            assert command_obj
+            use_prefix = ""
+            if command_name:
+                use_prefix += f"{command_name}"
+            docs += get_docs_for_click(
+                obj=command_obj, ctx=ctx, indent=indent + 1, call_prefix=use_prefix
+            )
+    return docs
+
+
+@app.command(help="Generate markdown version of usage documentation")
+def generate(
+    ctx: typer.Context,
+    name: str = typer.Option("", help="The name of the CLI program to use in docs."),
+    output: Path = typer.Option(
+        None,
+        help="An output file to write docs to, like README.md.",
+        file_okay=True,
+        dir_okay=False,
+    ),
+) -> None:
+    """
+    Generate Markdown docs for a Typer app.
+    """
+    from __main__ import app as main_app
+
+    click_obj = typer.main.get_command(main_app)
+    docs = get_docs_for_click(obj=click_obj, ctx=ctx, name=name)
+    clean_docs = f"{docs.strip()}\n"
+    if output:
+        output.write_text(clean_docs)
+        typer.echo(f"Docs saved to: {output}")
+    else:
+        typer.echo(clean_docs)

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "myoquant"
-version = "0.1.7"
+version = "0.1.9"
 description = "MyoQuant🔬: a tool to automatically quantify pathological features in muscle fiber histology images."
 authors = ["Corentin Meyer <[email protected]>"]
 maintainers = ["Corentin Meyer <[email protected]>"]